Release 0.1.0: CLI hardening, test coverage, release documentation by pmclSF · Pull Request #108 · pmclSF/terrain

pmclSF · 2026-04-01T20:05:54Z

Summary

Prepare Terrain 0.1.0 for release. Four logical commits covering the full CLI surface, test suite, documentation, and packaging.

refactor(cli): Harden CLI commands, fix bugs, improve consistency

Fix explain command flag parsing (flags after target were silently ignored)
Fix policy check JSON output (violations null → [])
Fix RuntimeFormats bounds check in terrain init
Fix formatSize producing garbage for sizes ≥ 10KB
Remove dead code across 6 files
Extract reportHelpers to eliminate 26x duplication in reporting package
Add progress reporting to 9 commands that were missing it
Run gofmt across 73 previously unformatted files
Add nil guards, defensive defaults, and bounds checks throughout

test: Improve test coverage, fix error handling in helpers

Add 12 new test files for CLI commands, structural detectors, pipeline helpers
Fix unchecked os.WriteFile errors in test write helpers
Update golden files to match current output format

docs: Update all documentation for 0.1.0 release

Rewrite CHANGELOG, README, quickstart, CLI spec, and CONTRIBUTING
Remove strategy-revealing docs from public tree (8 files → docs/internal/)
Remove all "Hamlet", "Stage NNN", "future hosted", and "/Users/" references
Sanitize benchmark artifact paths
All sample outputs verified against actual CLI

chore: Release packaging

Update LICENSE copyright to 2024-2026
Version consistency: 0.1.0 across package.json, vscode extension, CHANGELOG

Verification

go build ./... — PASS
go vet ./... — PASS
gofmt -l cmd/ internal/ — 0 files
go test ./... -count=1 — 48/48 packages pass
npm test — PASS (pack, install, CLI smoke, conversion smoke, migration smoke)
make extension-verify — PASS (compile + 4/4 tests)
make go-release-verify — PASS (vet, test, build, snapshot tests)
E2E: all 25+ commands verified against fixture repos with real output

Test plan

make go-release-verify passes
npm test passes
make extension-verify passes
Every CLI command produces correct output (verified in E2E run)
Zero strategy leaks in public documentation
Zero "hamlet" references (except Shakespeare test data)
Zero absolute filesystem paths in artifacts or docs

🤖 Generated with Claude Code

Replace redundant depgraph.Build(snapshot) calls with result.Graph in cmd_insights.go and cmd_impact.go. The graph is already built during RunPipeline and sealed in PipelineResult.Graph. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add branding block (icon: shield, color: green) required for GitHub Marketplace listing. Create README.md with usage examples, inputs/outputs documentation, full workflow example, and requirements. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add --format html to terrain analyze, producing a single self-contained HTML file with inline CSS and minimal JS. No external dependencies. Sections: summary cards, key findings with severity badges, signal breakdown, risk posture, coverage confidence bar, repository profile, data completeness, and limitations. Uses html/template from stdlib. Template is embedded as a Go string constant. Output is printable and shareable as a standalone file. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add local HTTP server for browser-based analysis viewing: - GET / serves HTML analysis report with 30s auto-refresh - GET /api/analyze returns analysis report as JSON - GET /api/health returns server status - Binds to 127.0.0.1:8421 (localhost only) - Cached pipeline result with 5s TTL to avoid redundant analysis - Graceful shutdown on SIGINT Usage: terrain serve --root . --port 8421 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

github-actions · 2026-04-01T20:09:04Z

[RISK] Terrain — Merge with caution

High-severity gaps found in changed code.

Metric	Value
Changed files	2544 (275 source, 2204 test)
Impacted units	799
Protection gaps	373
Tests to run	178 of 695 (25% of suite)

New Risks (directly changed)

[LOW] bin/postinstall.js: postinstall.js has no observed test coverage.
[LOW] bin/terrain-cli.js: terrain-cli.js has no observed test coverage.
[LOW] bin/terrain-compat.js: terrain-compat.js has no observed test coverage.
[MED] bin/terrain-installer.js: Exported function ensureTerrainBinary has no observed test coverage.
[MED] bin/terrain-installer.js: Exported function runTerrainCli has no observed test coverage.
[LOW] bin/terrain.js: terrain.js has no observed test coverage.
[LOW] cmd/terrain-convert-bench/main.go: main.go has no observed test coverage.
[LOW] cmd/terrain/cmd_ai.go: cmd_ai.go has no observed test coverage.
[LOW] cmd/terrain/cmd_analyze.go: cmd_analyze.go has no observed test coverage.
[LOW] cmd/terrain/cmd_compare.go: cmd_compare.go has no observed test coverage.
... and 363 more (4 high, 225 medium, 134 low)

Pre-existing issues on changed files (204)

internal/analysis/ai_context_infer.go: [uncoveredAISurface] AI prompt 'message_array' has zero test or scenario coverage. Changes to this surface can alter AI behavior without any safety net.
internal/analysis/prompt_ast_parser.go: [uncoveredAISurface] AI prompt 'message_array' has zero test or scenario coverage. Changes to this surface can alter AI behavior without any safety net.
internal/analysis/prompt_parser.go: [uncoveredAISurface] AI prompt 'backtick_prompt' has zero test or scenario coverage. Changes to this surface can alter AI behavior without any safety net.
internal/analysis/prompt_parser.go: [uncoveredAISurface] AI prompt 'message_array' has zero test or scenario coverage. Changes to this surface can alter AI behavior without any safety net.
internal/analysis/structural_parser.go: [uncoveredAISurface] AI prompt 'backtick_prompt' has zero test or scenario coverage. Changes to this surface can alter AI behavior without any safety net.
... and 199 more

Recommended Tests

178 test(s) with exact coverage of 406 impacted unit(s). 393 impacted unit(s) have no covering tests in the selected set.

Package	Tests	Sample
`internal/convert`	41	`internal/convert/all_directions_smoke_test.go ...`
`internal/analysis`	22	`internal/analysis/ai_context_infer_test.go ...`
`cmd/terrain`	11	`cmd/terrain/ai_workflow_test.go ...`
`internal/depgraph`	10	`internal/depgraph/bench_test.go ...`
`internal/engine`	10	`internal/engine/adversarial_test.go ...`
`internal/reporting`	10	`internal/reporting/analyze_report_test.go ...`
`internal/testdata`	10	`internal/testdata/adversarial_test.go ...`
`internal/models`	7	`internal/models/changeset_test.go ...`
`internal/analyze`	5	`internal/analyze/actions_test.go ...`
`internal/ownership`	4	`internal/ownership/aggregate_test.go ...`
`internal/impact`	3	`internal/impact/changeset_builder_test.go ...`
`internal/migration`	3	`internal/migration/detectors_test.go ...`
`internal/truthcheck`	3	`internal/truthcheck/calibrate_cmd_test.go ...`
`internal/aidetect`	2	`internal/aidetect/detect_extra_test.go ...`
`internal/benchmark`	2	`internal/benchmark/bench_test.go ...`
`internal/changescope`	2	`internal/changescope/changescope_test.go ...`
`internal/explain`	2	`internal/explain/explain_golden_test.go ...`
`internal/insights`	2	`internal/insights/insights_golden_test.go ...`
`internal/measurement`	2	`internal/measurement/measurement_test.go ...`
`internal/quality`	2	`internal/quality/snapshot_heavy_test.go ...`
`internal/scoring`	2	`internal/scoring/risk_engine_benchmark_test.go ...`
`internal/signals`	2	`internal/signals/detector_registry_test.go ...`
`cmd/terrain-convert-bench`	1	`cmd/terrain-convert-bench/main_test.go`
`internal/airun`	1	`internal/airun/artifact_test.go`
`internal/comparison`	1	`internal/comparison/compare_test.go`
`internal/gauntlet`	1	`internal/gauntlet/ingest_test.go`
`internal/governance`	1	`internal/governance/evaluate_test.go`
`internal/graph`	1	`internal/graph/graph_test.go`
`internal/health`	1	`internal/health/detectors_test.go`
`internal/heatmap`	1	`internal/heatmap/heatmap_test.go`
`internal/identity`	1	`internal/identity/identity_test.go`
`internal/lifecycle`	1	`internal/lifecycle/lifecycle_test.go`
`internal/matrix`	1	`internal/matrix/matrix_test.go`
`internal/metrics`	1	`internal/metrics/metrics_test.go`
`internal/plugin`	1	`internal/plugin/plugin_test.go`
`internal/portfolio`	1	`internal/portfolio/portfolio_test.go`
`internal/sarif`	1	`internal/sarif/convert_test.go`
`internal/server`	1	`internal/server/server_test.go`
`internal/skipstats`	1	`internal/skipstats/summary_test.go`
`internal/stability`	1	`internal/stability/cluster_test.go`
`internal/structural`	1	`internal/structural/structural_test.go`
`internal/summary`	1	`internal/summary/executive_test.go`
`internal/telemetry`	1	`internal/telemetry/telemetry_test.go`

Owners: pmclachlansf

Limitations

No coverage artifacts provided; protection gaps reflect missing data, not measured absence. Provide --coverage to improve accuracy.
Mixed test cultures reduce cross-framework optimization confidence. Consider standardizing on fewer frameworks.

Terrain — terrain pr --json for full machine-readable results

Targeted Test Results

Terrain selected 178 test(s) instead of the full suite.

Go tests: passed

Auto-detect device farm configurations for two additional providers: Sauce Labs (.sauce/config.yml): - Parse suites[].capabilities for platformName, browserName, deviceName - Create DeviceConfig entries with InferredFrom: "saucelabs" - Create envclass:saucelabs-device EnvironmentClass Firebase Test Lab (firebase.json with testlab field): - Parse devices[] for model, version, locale - Create DeviceConfig entries with InferredFrom: "firebase-testlab" - Create envclass:firebase-device EnvironmentClass Both integrate into existing ParseFrameworkMatrices() — no pipeline changes. Silently skip when config files are absent (zero-config principle). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add ability to compare eval metrics between baseline and current state: - CompareEvalMetrics() in internal/comparison: compares per-scenario metrics, classifies regressions (accuracy-like: lower is worse; cost/latency-like: higher is worse), sorts regressions first - EvalMetricDelta type with ScenarioID, MetricName, Delta, IsRegression - terrain ai baseline compare command: loads baseline, runs current analysis, compares scenario counts (added/removed) and metrics - Supports --json output for CI integration - Human-readable output with regression markers Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

HTML report: - Add section-level assertions (signal summary, coverage, risk posture, data completeness, total finding count overflow message) - Add XSS/escaping test (html/template escapes script tags and quotes) Sauce Labs detection: - Add empty suites test (zero devices for empty array) - Add malformed YAML test (no panic, graceful skip) - Add alternate path test (.sauce.yml in root) CLI smoke tests: - Add terrain ai baseline compare smoke test (verifies no panic) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Code quality and bug fixes across all CLI commands and internal packages: - Fix explain command flag parsing (flags after target were silently ignored) - Fix policy check JSON output (violations serialized as null instead of []) - Fix RuntimeFormats bounds check in terrain init - Fix formatSize producing garbage output for sizes >= 10KB - Fix directionFromKey panic on malformed input - Remove dead code: executeJestToVitest*, populateLinkedCodeUnits, detectFirstExisting, wordBoundaryCache, filecache_consumers duplicates - Extract reportHelpers to eliminate 26x line/blank closure duplication - Replace custom filepathDir with filepath.Dir - Replace O(n) LookupDirection with O(1) map lookup - Add progress reporting to all analysis commands consistently - Pass verbose flag through to RenderPortfolioReport and RenderMetricsReport - Add defensive default case in runShow switch - Rename shadowing variable in runAnalyze - Add nil guard in isUniqueCodeUnitName and DetectEdgeCases - Merge double signal scan in topFilesForType - Replace triple-nested class lookup with map in matrix.go - Consolidate hasPromptPatterns/hasDatasetPatterns into generic helper - Replace custom sortStrings with sort.Strings - Fix resolveConfigValidationMode unreachable code path - Add filepath.Abs error handling in cmd_serve and cmd_insights - Add os.Stdout.Write error check in cmd_ai - Run gofmt across all 73 previously unformatted files - Use reorderCLIArgs for explain command (supports flags in any position) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Add test coverage for CLI commands (ai, analyze, convert validation) - Add tests for structural detectors, pipeline helpers, depgraph building - Add tests for convert execution dispatch, parallel conversion, validation modes - Add tests for code surface model and aidetect edge cases - Fix unchecked os.WriteFile errors in test write helpers - Update golden files to match current output format - Remove test for deleted detectFirstExisting function Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Rewrite CHANGELOG for 0.1.0 (from incorrect 2.0.0) - Update README: sample outputs match actual CLI, trim architecture section, reorder Documentation before Development, remove stale hamlet-converter reference - Update cli-spec.md: add --gauntlet, --format, --verbose flags; add conversion/migration command section; fix duplicate entries - Update quickstart.md: add "What Terrain detects" section, concrete explain examples - Update CONTRIBUTING.md: current package count, command conventions, testing conventions - Update DESIGN.md: remove stale roadmap link, trim package listing - Remove strategy-revealing docs from public tree: roadmap.md, release-checklist.md, launch-assets.md, phased-implementation-roadmap.md, ui-requirements.md, positioning.md, feature-matrix.md, persona-matrix.md - Remove all "Stage NNN" references from user-facing docs - Remove all "future hosted" / "paid product" language - Remove "promote" subcommand references (not implemented) - Fix "XCTest/Espresso" overpromise in Who Uses Terrain - Update validation dates in product docs - Sanitize benchmark artifact paths (remove /Users/ and hamlet) - Remove stale internal cleanup docs - Fix telemetry.md example version (3.1.0 → 0.1.0) - Fix supply-chain.md examples (1.0.0 → 0.1.0) - Fix broken links to moved files across architecture docs Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Update LICENSE copyright to 2024-2026 - Ensure package.json and vscode extension at 0.1.0 - Align goreleaser config Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

pmclSF and others added 4 commits April 1, 2026 13:05

pmclSF and others added 2 commits April 1, 2026 13:30

pmclSF changed the title ~~feat: Phase 3 — HTML reports, terrain serve, graph reuse, marketplace action~~ feat: Phase 3 complete — HTML reports, serve, graph reuse, marketplace, device farms, eval compare Apr 1, 2026

pmclSF and others added 21 commits April 1, 2026 13:45

feat: package terrain for npm and homebrew release

6bf8008

feat: add go-native conversion runtime for js migrations

59b386b

test: stabilize server handler fixtures

a45588d

feat: add go-native conversion runtime for java and python migrations

796803c

feat: add go-native migration workflow commands

466b3c8

feat: retire legacy javascript runtime and tests

6d7f4ef

docs: retire stale legacy runtime guidance

e136c88

docs: mark retired engineering packages as historical

1c3c9d7

feat: harden go-native converter parity and ast coverage

9ba6b3a

feat: reduce java and python conversion TODOs

e9e54d5

Complete native migration runtime and harden JS converters

c1121e8

Raise go-native migration fidelity and safety

9158d30

Close JS config parity and raise converter quality gates

829bac6

Raise JS migration validation and mixed-repo safety

6054051

Make JS migration validation modes explicit

78ab05a

Improve JS detection evidence and config CLI parity

ce5e153

chore: Update license year and release packaging for 0.1.0

47172ea

- Update LICENSE copyright to 2024-2026 - Ensure package.json and vscode extension at 0.1.0 - Align goreleaser config Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

pmclSF changed the title ~~feat: Phase 3 complete — HTML reports, serve, graph reuse, marketplace, device farms, eval compare~~ Release 0.1.0: CLI hardening, test coverage, release documentation Apr 7, 2026

pmclSF merged commit 73e19bd into main Apr 7, 2026
9 checks passed

pmclSF deleted the feat/phase3-features branch April 7, 2026 05:14

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Release 0.1.0: CLI hardening, test coverage, release documentation#108

Release 0.1.0: CLI hardening, test coverage, release documentation#108
pmclSF merged 27 commits intomainfrom
feat/phase3-features

pmclSF commented Apr 1, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Apr 1, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

pmclSF commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

refactor(cli): Harden CLI commands, fix bugs, improve consistency

test: Improve test coverage, fix error handling in helpers

docs: Update all documentation for 0.1.0 release

chore: Release packaging

Verification

Test plan

Uh oh!

github-actions bot commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

[RISK] Terrain — Merge with caution

New Risks (directly changed)

Recommended Tests

Targeted Test Results

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

pmclSF commented Apr 1, 2026 •

edited

Loading

github-actions bot commented Apr 1, 2026 •

edited

Loading