feat: release Shipcheck v0.1.0

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,19 @@
+name: Bug report
+description: Report a reproducible Shipcheck defect
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Reproduction
+    validations:
+      required: true
+  - type: input
+    id: node
+    attributes:
+      label: Node.js version

.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Problem
+
+## Changes
+
+## Validation
+
+- [ ] lint
+- [ ] typecheck
+- [ ] tests
+- [ ] build
+- [ ] package smoke test
+- [ ] self-check
+
+## Security and limitations

.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        node: [20, 24]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+      - run: npm ci
+      - run: npm install --global typescript@5.8.3
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm test
+      - run: npm run build
+      - run: node dist/cli.js . --ci
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm install --global typescript@5.8.3
+      - run: npm run test:coverage
+      - run: npm pack
+      - run: node scripts/package-smoke.mjs shipcheck-0.1.0.tgz
+      - run: npm audit --audit-level=high

.github/workflows/codeql.yml

@@ -0,0 +1,22 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: "17 3 * * 1"
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: github/codeql-action/init@v3
+        with:
+          languages: javascript-typescript
+      - uses: github/codeql-action/analyze@v3

.gitignore

@@ -3,9 +3,8 @@ dist/
 artifacts/
 coverage/
 *.tgz
-*.zip
-!tests/fixtures/**/*.zip
 shipcheck-report.md
+tests/fixtures/*
+!tests/fixtures/README.md
 .DS_Store
 .env
-!tests/fixtures/forbidden-file-present/.env

CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [0.1.0] - 2026-07-22
+
+### Added
+
+- Version consistency checks for package, extension, and arbitrary JSON sources.
+- Contextual README release-version drift detection.
+- CHANGELOG validation for current, duplicate, parseable, and ordered headings.
+- Artifact filename, stale artifact, ZIP internal manifest, and forbidden-entry checks.
+- Terminal, JSON, and Markdown reporters with stable exit codes.
+- Safe configuration initialization, JSON Schema, fixtures, tests, and cross-platform CI.

CODE_OF_CONDUCT.md

@@ -0,0 +1,19 @@
+# Contributor Covenant Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in this project a harassment-free experience for everyone, regardless of background or identity.
+
+## Expected behavior
+
+Use welcoming and inclusive language, respect differing viewpoints, accept constructive feedback, focus on what is best for the community, and show empathy toward other contributors.
+
+## Unacceptable behavior
+
+Harassment, discriminatory language, personal attacks, publishing private information, and other conduct inappropriate in a professional setting are not acceptable.
+
+## Enforcement
+
+Report unacceptable behavior privately to the project maintainers. Maintainers may remove, edit, or reject contributions and may temporarily or permanently ban contributors whose behavior is harmful.
+
+This policy is adapted from Contributor Covenant version 2.1.

CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contributing
+
+## Development setup
+
+Use Node.js 20 or newer and TypeScript 5.8.3. Run `npm ci`, install the pinned TypeScript compiler globally, then run the full validation sequence documented in README.
+
+## Changes
+
+Keep checks deterministic, read-only, and free of network access. Add a meaningful fixture and tests for each new rule or failure mode. Do not weaken path, ZIP, or resource-limit checks to make an unusual archive pass.
+
+## Pull requests
+
+Describe the release problem being solved, user-visible behavior, tests, security implications, and limitations. Keep unrelated refactors separate. All CI jobs must pass on Ubuntu, Windows, and macOS.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shipcheck contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,178 @@
+# Shipcheck
+
+Catch version, documentation, and release artifact drift before you ship.
+
+Shipcheck is a local-first, deterministic command-line tool for checking whether a repository's version sources, release documentation, and packaged artifacts agree with each other. It reads project files only; it does not execute scanned project code, upload files, require an account, or send telemetry.
+
+## Why Shipcheck
+
+A package manifest, browser-extension manifest, README, CHANGELOG, and release ZIP can each be valid while describing different releases. Those errors are easy to miss in manual review and often appear only after a user downloads the wrong artifact. Shipcheck turns that drift into repeatable local and CI checks.
+
+## Features
+
+- Compare versions from `package.json`, Chrome Extension `manifest.json`, or any configured JSON path.
+- Detect stale release versions in README installation commands, links, badges, and ZIP names.
+- Validate CHANGELOG presence, current-version coverage, duplicate headings, parseable headings, and descending order.
+- Verify artifact filenames and identify likely stale artifacts beside the current file.
+- Inspect required JSON files inside ZIP archives, including archives with one wrapper directory.
+- Reject unsafe ZIP paths, symbolic-link entries, encrypted entries, oversized entries, and configured forbidden content.
+- Check required and forbidden repository files.
+- Produce terminal, JSON, or Markdown reports from one result model.
+- Use stable exit codes for shell scripts and CI.
+
+## Quick start
+
+The npm package is not published yet. The following development installation has been verified:
+
+```bash
+git clone https://github.com/kodlbegiko/shipcheck.git
+cd shipcheck
+npm ci
+npm install --global typescript@5.8.3
+npm run build
+node dist/cli.js init ../your-project
+node dist/cli.js ../your-project
+```
+
+After an npm release, the intended commands are:
+
+```bash
+npx shipcheck
+npx shipcheck .
+npx shipcheck --config shipcheck.config.json
+npx shipcheck --format json
+npx shipcheck --format markdown --output shipcheck-report.md
+npx shipcheck --ci
+npx shipcheck init
+```
+
+`shipcheck init` never overwrites an existing configuration unless `--force` is supplied.
+
+## Configuration
+
+```json
+{
+  "$schema": "./schema/shipcheck.schema.json",
+  "versionSources": [
+    { "file": "package.json", "path": "version", "primary": true },
+    { "file": "manifest.json", "path": "version" }
+  ],
+  "documents": {
+    "readme": "README.md",
+    "changelog": "CHANGELOG.md",
+    "changelogRequired": true
+  },
+  "artifacts": [
+    {
+      "file": "dist/example-v{version}.zip",
+      "versionPattern": "v?(?<version>\\d+\\.\\d+\\.\\d+)",
+      "internalVersionSources": [
+        { "file": "manifest.json", "path": "version" }
+      ]
+    }
+  ],
+  "requiredFiles": ["README.md", "LICENSE", "CHANGELOG.md"],
+  "forbiddenFiles": [".env", ".DS_Store"]
+}
+```
+
+Unknown configuration fields are rejected. Absolute paths and paths outside the project root are rejected. See [configuration](docs/configuration.md) for the complete schema.
+
+## Example terminal output
+
+```text
+Shipcheck 0.1.0 — FAIL
+Project: /workspace/example
+Version: 0.1.0
+
+ERROR   VERSION_SOURCE_MISMATCH manifest.json: Version source does not match the primary version
+         expected=0.1.0 actual=0.0.9
+         fix: Update version to 0.1.0.
+
+Summary: 1 error(s), 0 warning(s), 0 info
+```
+
+## Supported checks
+
+The rule catalogue, severities, and remediation guidance are documented in [rules](docs/rules.md).
+
+## GitHub Actions
+
+Until npm publication, use a checked-out copy of Shipcheck:
+
+```yaml
+name: Shipcheck
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  release-consistency:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: project
+      - uses: actions/checkout@v4
+        with:
+          repository: kodlbegiko/shipcheck
+          ref: v0.1.0
+          path: shipcheck
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+        working-directory: shipcheck
+      - run: npm install --global typescript@5.8.3
+      - run: npm run build
+        working-directory: shipcheck
+      - run: node ../shipcheck/dist/cli.js . --ci
+        working-directory: project
+```
+
+Actions use major tags in this repository so trusted official actions receive compatible security fixes. Pin to full commit SHAs where organizational policy requires immutable references.
+
+## Exit codes
+
+| Code | Meaning |
+|---:|---|
+| 0 | Checks completed with no blocking errors. |
+| 1 | Checks completed and at least one blocking error was found. |
+| 2 | Shipcheck could not run because of invalid configuration, invalid CLI usage, or an internal failure. |
+
+Warnings do not block by default. Use `--warnings-as-errors` or `warningsAsErrors` in configuration to make them blocking.
+
+## Limitations
+
+Shipcheck intentionally supports JSON configuration only. README detection is contextual and may require documentation changes when a version-like token is intentionally historical. ZIP support is limited to standard single-disk archives using stored or DEFLATE entries; ZIP64 and encrypted archives are rejected. See [limitations](docs/limitations.md).
+
+## Security model
+
+Shipcheck treats scanned repositories and ZIP files as untrusted data. It does not import project configuration, execute project scripts, extract ZIP content, follow symlinks, access paths outside the selected root, or make network requests. Resource limits reduce risk but do not make Shipcheck a general malware or supply-chain scanner. See [SECURITY.md](SECURITY.md).
+
+## Development
+
+```bash
+npm ci
+npm install --global typescript@5.8.3
+npm run lint
+npm run typecheck
+npm test
+npm run test:coverage
+npm run build
+npm pack
+node scripts/package-smoke.mjs shipcheck-0.1.0.tgz
+node dist/cli.js .
+npm audit
+```
+
+The repository uses TypeScript with strict settings. Runtime code has no third-party dependencies. Tests use the Node.js test runner to keep package installation deterministic and offline after checkout.
+
+## Contributing
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Reports involving a vulnerability should follow [SECURITY.md](SECURITY.md), not a public issue.
+
+## License
+
+MIT

SECURITY.md

@@ -0,0 +1,19 @@
+# Security policy
+
+## Supported versions
+
+The current minor release is supported with security fixes.
+
+## Reporting
+
+Report suspected vulnerabilities privately through GitHub's security advisory interface when available. Do not include secrets, private repositories, or malicious archives in a public issue.
+
+## Security boundaries
+
+Shipcheck parses data files only. It does not execute scanned repositories, load JavaScript configuration, extract ZIP entries, or access paths outside the selected project root. ZIP inspection enforces entry-count, central-directory, entry-name, compression-method, and uncompressed-size limits. It rejects encrypted archives, symlink entries, unsafe paths, and unsupported ZIP structures.
+
+These controls reduce exposure to malformed input but do not prove that an archive is safe. Shipcheck is not an antivirus product, dependency scanner, or complete supply-chain defense.
+
+## Dependencies
+
+Runtime code intentionally has no third-party dependencies. GitHub Actions use official actions at explicit major versions; this permits compatible security updates but is less immutable than a full commit SHA.