@stsepelin/checktrail 0.1.0-alpha.2 → 0.1.0-alpha.4

package/docs/SETUP-SCOPES.md

@@ -0,0 +1,107 @@
+# Choose and understand setup coverage
+
+A repository can contain a runnable library, a documentation project and CI
+workflows. Each can need different tools. `init` proposes checks; `doctor` reports
+static setup gaps; only a trusted `run` produces validation evidence.
+
+Use the [installation guide](INSTALLATION.md) and inspect before writing:
+
+```sh
+checktrail init --root "$PWD"
+checktrail plan --root "$PWD" --detailed
+checktrail doctor --root "$PWD" --detailed
+```
+
+A `needs-selection` or `attention-required` result exits `2`. Read its JSON before
+choosing checks. These inspection commands do not run project scripts or install
+dependencies. Detailed output includes paths and may include absolute diagnostic paths.
+
+## A library with documentation and workflows
+
+Consider this original, generic repository:
+
+```text
+package.json                    scripts.test is "node --test"
+sum.test.js                     one passing Node test
+.github/workflows/verify.yml    a GitHub Actions workflow
+docs/requirements.txt           documentation dependencies
+docs/conf.py                    documentation configuration, no tests
+```
+
+Discovery identifies JavaScript and infrastructure at `.`, and Python at `docs`.
+The directory name does not prove that it is documentation, nor that it can be
+ignored: the operator knows its purpose. Checktrail does not infer a documentation
+build command from a Python manifest.
+
+`init` returns `needs-selection` for the Python project and writes nothing, even
+though the Node test command is recognized. Supplying a check for `.` does not
+select it for nested projects. For example, this explicit preview covers all three
+discovered ecosystems:
+
+```sh
+checktrail init --root "$PWD" \
+  --check '.#javascript.node-test' \
+  --check '.#infrastructure.actionlint' \
+  --check 'docs#python.unittest'
+```
+
+It produces a policy preview, but the choice of `unittest` is not evidence of tests
+in `docs`. If that policy is created with `--write`, `doctor --detailed` reports
+`unavailable-check` for `python.unittest`: no candidate test files were discovered.
+Choosing a runner merely to resolve setup selection does not validate documentation.
+Use a separately supported check or the project's own documentation build; keep
+that work outside Checktrail's coverage claim when no applicable adapter exists.
+
+## Prepare workflow validation separately
+
+`infrastructure.actionlint` is static workflow analysis. It does not execute CI
+jobs or validate their shell bodies. It needs both the prepared native executable
+and `checktrail.actionlint.json` beside the workflow repository root:
+
+```json
+{
+  "schemaVersion": 1,
+  "runnerLabels": [],
+  "variables": []
+}
+```
+
+The empty arrays declare no extra runner labels or configuration variables. Review
+actual workflow requirements before adopting those values. See [ACTIONLINT.md](ACTIONLINT.md)
+for the supported tool version, configuration, dependency checks and limitations.
+Without this configuration, diagnosis reports `unavailable-check`; without an
+executable on the effective PATH it also reports `missing-executable`. Prepare the
+tool explicitly, then repeat diagnosis. A successful Node test cannot supply this
+workflow evidence.
+
+## Interpret an intentionally narrowed policy
+
+After reviewing the desired scope, an operator may explicitly maintain a
+language-only policy. For the example above, it is:
+
+```json
+{
+  "schemaVersion": 1,
+  "projects": [{ "path": ".", "checks": ["javascript.node-test"] }]
+}
+```
+
+Edit an existing policy deliberately; `init --write` preserves it and cannot
+replace it or narrow its checks through `--check` arguments. Do not discard
+existing overlays, packs, environment requirements or workspace dependencies.
+
+With the language-only policy, the commands have different meanings:
+
+| Command                                                   | Result for this example                                                                             | Coverage                                               |
+| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `checktrail doctor --root "$PWD" --detailed`              | `attention-required`, exit `2`; `unselected-project` for infrastructure at `.` and Python at `docs` | Workflow and documentation-project checks are omitted. |
+| `checktrail run --root "$PWD" --trust-project --detailed` | `passed`, exit `0`, if the Node test passes                                                         | The selected Node test only.                           |
+
+These results are consistent: validation passed its selected check while diagnosis
+reported broader discovered scope left unselected. `doctor` does not assess every
+possible check within a selected ecosystem either; selecting Node tests does not
+claim linting, typing, browser behavior or documentation coverage.
+
+Keep omitted work visible in your review and CI requirements. The
+[public adoption report](PUBLIC-ADOPTION.md) records these distinctions on pinned
+public projects; its historical results are not a claim about your repository.

package/docs/STATUS.md

@@ -3,15 +3,38 @@
 This is an experimental foundation with public source at
 [stsepelin/checktrail](https://github.com/stsepelin/checktrail).
 Check the [installation guide](INSTALLATION.md) for package availability and setup.
-The `0.1.0-alpha.1` preview is published on npm. The newer
-[hosted run at bfc8cc4](https://github.com/stsepelin/checktrail/actions/runs/35585998184)
-passed all jobs; earlier toolchain evidence remains in `NATIVE-CI.md`.
-The alpha.2 candidate adds setup commands and requires its own release CI and
-publication. MCP Registry registration remains pending.
+The `0.1.0-alpha.3` preview is published on npm and active in the MCP Registry.
+The [hosted run at b0b447d](https://github.com/stsepelin/checktrail/actions/runs/35597877167)
+passed all jobs. The published tarball matched the reviewed artifact; fresh
+registry installation, CLI/library validation, generated npx startup and MCP
+execution/trust behavior were verified. Earlier toolchain evidence remains in
+`NATIVE-CI.md`; release details and tag limitations are in `RELEASE.md`.
+The GitHub alpha.3 prerelease includes the verified artifact and checksum.
+[Public adoption](PUBLIC-ADOPTION.md) records alpha.2 on five pinned libraries, including incomplete
+coverage and the TypeScript 4.9.5 incompatibility fixed in alpha.3.
+
+## Alpha.4 candidate (unpublished)
+
+The checkout version is `0.1.0-alpha.4`. Release verification is in progress;
+alpha.3 remains the published preview. No alpha.4 publication or hosted release
+verification is claimed.
+
+- [Go scope policy](GO-SCOPE.md): exact per-file declarations can acknowledge
+  native build-constraint exclusions. Go must confirm every exemption; stale
+  declarations and other omissions remain incomplete. Detailed reports retain
+  reasons and summaries show counts. Formatting still covers all source. Race
+  package listing now uses the same `-race` constraints as execution.
+
+## Alpha.3 release
+
+- [TypeScript compatibility](TYPESCRIPT.md): plain typechecking now passes the
+  native 4.9.5 regression while retaining the 6.0.3 `noCheck` override and native
+  file accounting. A packed CLI/library/MCP replay fixes the recorded mitt case.
+  Published alpha.2 and its immutable adoption record retain the original failure.
 
 ## Implemented
 
-- Alpha.2 candidate: conservative multi-language `init`, execution-free `doctor`,
+- Alpha.2: conservative multi-language `init`, execution-free `doctor`,
   and version-pinned MCP configuration output for Codex, Claude Code/Desktop,
   Cursor and VS Code. Existing files are preserved. See [ONBOARDING.md](ONBOARDING.md)
   for scope, ambiguity handling and package upgrade/rollback verification.
@@ -153,11 +176,10 @@ a general speedup/graph-completeness claim.
 
 ## Release preparation
 
-`server.json` and npm `mcpName` describe the `0.1.0-alpha.1` preview.
-The metadata passed the pinned official registry schema; a native SDK-client test
-starts its command and verifies execution remains disabled. This does not establish
-registry acceptance or npm publication. Hosted source evidence is recorded
-separately in `NATIVE-CI.md`. See `RELEASE.md`.
+`server.json`, the npm package and the engine identify the published
+`0.1.0-alpha.3` preview. Its source commit passed hosted CI, the published tarball
+matched the reviewed artifact, and fresh CLI/library/MCP installation checks passed.
+Publication evidence and the sequence for future releases are in `RELEASE.md`.
 
 ## Pinned pack distribution
 

package/docs/TYPESCRIPT.md

@@ -0,0 +1,78 @@
+# TypeScript compiler compatibility
+
+The source checkout's `javascript.typescript` profile now supports the exercised
+TypeScript 4.9.5 and 6.0.3 configurations. This fix is published in
+**0.1.0-alpha.3**. Published alpha.2 still passes an option that
+TypeScript 4.9.5 rejects. The original
+[public adoption record](PUBLIC-ADOPTION.md) remains unchanged as release evidence.
+Other compiler versions require their own native verification.
+
+## Invocation and boundaries
+
+Planning locates the project-local or root-hoisted compiler without importing it.
+During explicitly trusted execution, a runner loads the selected compiler API
+and uses its public command-line parser to check support for `--noCheck false`.
+Supported compilers receive that override, so `noCheck: true` cannot disable the
+selected type check. Older compilers that reject this option receive the remaining
+arguments; an unexpected capability response stops before the compiler CLI starts.
+The probe parses fixed arguments and does not parse project configuration.
+
+The compiler entry and API must resolve inside the configured root. They are
+trusted executable dependencies; this check is not a sandbox. No compiler is
+installed or downloaded during planning or execution. `doctor` remains static
+and does not perform this runtime capability probe.
+
+Checks still disable emitted output and incremental state and require every
+inventoried TypeScript source in the native file list. A successful compiler exit
+with omitted source is incomplete. A legacy compiler's unsupported project options
+remain compiler errors; the runner does not rewrite `tsconfig.json`.
+
+The Vue runner uses the same capability helper. Its separately tested Vue 3.5.43,
+vue-tsc 3.3.11 and TypeScript 6.0.3 profile retains type-error detection and the
+`skipTemplateCodegen` rejection. This does not establish legacy Vue compatibility.
+The solution-build adapter remains gated to TypeScript 6.0.3; see
+[TYPESCRIPT-BUILD.md](TYPESCRIPT-BUILD.md).
+
+## Verification
+
+The new 4.9.5 regression failed on the previous adapter's TS5023 error. With this
+change it accepts valid code, rejects a real TS2322 error, accounts for excluded
+source, identifies the actual tool version, supports a root-hoisted compiler and
+paths with spaces, and leaves emitted/incremental files absent. Existing native
+6.0.3 and Vue regressions still reject type errors even with `noCheck: true`.
+Separate regressions reject an escaping compiler API and an ambiguous capability
+response before the compiler CLI executes. Planning is checked against executable
+traps in both the CLI and API files.
+
+The [known-case replay](measurements/typescript-legacy-replay.json) uses mitt at
+the same pinned revision and the same TypeScript 4.9.5 tool profile as the alpha.2
+adoption exercise. After generating its required root declaration, native checking
+and the packed fix pass; an original injected TS2322 error fails through the CLI,
+library and MCP. The policy and tracked upstream files stay unchanged, and the
+injected source and generated declaration are removed afterwards. This is a
+regression replay after observing the failure, not a new independent holdout.
+The record identifies the tested local tarball and adapter source hashes; it is
+not the published alpha.2 artifact.
+
+## Prepare the legacy regression
+
+The old compiler has a separate locked installation so its `tsc` binary cannot
+replace the compiler used to build Checktrail:
+
+```sh
+mkdir -p .checktrail/typescript-legacy-tools
+cp scripts/typescript-legacy-tools/package.json scripts/typescript-legacy-tools/package-lock.json .checktrail/typescript-legacy-tools/
+npm ci --prefix .checktrail/typescript-legacy-tools --ignore-scripts --no-audit --no-fund
+npm run build
+node --test dist/test/typescript.test.js dist/test/vue-tsc.test.js dist/test/typescript-build.test.js
+```
+
+The general suite explicitly skips the legacy native case when this installation
+is absent. The hosted main matrix prepares it and the `javascript` required-native
+profile rejects a skipped or missing legacy regression. A local pass does not
+establish hosted CI results.
+
+TypeScript introduced the public `noCheck` option in
+[TypeScript 5.6](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-6.html#the--nocheck-option).
+The runner checks actual parser behavior instead of assuming capabilities from a
+package version string.

package/docs/measurements/go-scope-policy-replay.json

@@ -0,0 +1,91 @@
+{
+  "scope": "Known-case replay of an unreleased local package; excludes the JavaScript target without validating it; not an independent holdout",
+  "upstreamCommit": "2d3c2a9cc518326daf99a383f07c4d3c44317e4d",
+  "tarballSha256": "08069a85dc7863394a88218a1670a2e00381c7e176a1ae4c987ce8496a4c3e19",
+  "platform": "darwin",
+  "arch": "arm64",
+  "node": "v26.8.1",
+  "observations": [
+    {
+      "phase": "strict",
+      "outcome": "failed",
+      "checks": [
+        {
+          "id": "go.format",
+          "status": "failed"
+        },
+        {
+          "id": "go.vet",
+          "status": "inconclusive"
+        },
+        {
+          "id": "go.test",
+          "status": "inconclusive"
+        }
+      ],
+      "mcpCounts": [0, 0, 0]
+    },
+    {
+      "phase": "declared",
+      "outcome": "failed",
+      "checks": [
+        {
+          "id": "go.format",
+          "status": "failed"
+        },
+        {
+          "id": "go.vet",
+          "status": "passed"
+        },
+        {
+          "id": "go.test",
+          "status": "passed",
+          "tests": {
+            "total": 213,
+            "passed": 212,
+            "failed": 0,
+            "skipped": 1
+          }
+        }
+      ],
+      "mcpCounts": [0, 1, 1]
+    },
+    {
+      "phase": "failing-test",
+      "outcome": "failed",
+      "checks": [
+        {
+          "id": "go.format",
+          "status": "failed"
+        },
+        {
+          "id": "go.vet",
+          "status": "passed"
+        },
+        {
+          "id": "go.test",
+          "status": "failed",
+          "tests": {
+            "total": 214,
+            "passed": 212,
+            "failed": 1,
+            "skipped": 1
+          }
+        }
+      ],
+      "mcpCounts": [0, 1, 1]
+    }
+  ],
+  "baseCommit": "bc0b95a511706475df97d1472b4724b36dbc2848",
+  "goVersion": "go version go1.27.1 darwin/arm64",
+  "sources": {
+    "src/go-scope-policy.ts": "be40a2fa681fd5c320e36ea4608a972cb369e045227e1e3fd539f915444287f3",
+    "src/go-scope.ts": "cc85c48962b91ab4b88977a78f8bddc62e866f8d863c265ffe1b1cfd523a4895",
+    "src/adapters.ts": "ba2dab60ac9ecf20d9843285b614d62b4853f06972e2e27946fe0f8de01c4a61",
+    "src/evidence.ts": "477a82d4b40cb3480fa9d5b6ab2a0d41c06685f275fda0abb061219eb2a7a086",
+    "src/output.ts": "6befd79c5cc095137edd5b11c6f29622ffa22f9d924ed64152a085abef7da891",
+    "src/schemas.ts": "e5add92fee2727e50222757703c8dd786b72c6ebf2b40d1fcad4864961805ee2",
+    "src/types.ts": "c30a5c65903342148a7a07c210d6c0b5231295bbf7b1d94944a29c070289587c"
+  },
+  "harnessSha256": "acd5dcad4cc8fce8818963f48714cc8af8139720f64779a2dbc79d6fb4866c3f"
+}