oss-pulse 0.1.0

package/dist/sarif.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sarif.d.ts","sourceRoot":"","sources":["../src/sarif.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAyB,WAAW,EAAE,MAAM,YAAY,CAAA;AAuDpE,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAsBvD"}

package/dist/sarif.js

@@ -0,0 +1,74 @@
+import { pathToFileURL } from "node:url";
+import { artifactUriForAction } from "./action-artifacts.js";
+const SOURCE_ROOT_URI_BASE_ID = "%SRCROOT%";
+export function formatSarif(report) {
+    const log = {
+        $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+        runs: [
+            {
+                originalUriBaseIds: {
+                    [SOURCE_ROOT_URI_BASE_ID]: { uri: rootUri(report.root) },
+                },
+                results: report.actions.map(formatResult),
+                tool: {
+                    driver: {
+                        name: "oss-pulse",
+                        rules: report.actions.map(formatRule),
+                        semanticVersion: "0.1.0",
+                    },
+                },
+            },
+        ],
+        version: "2.1.0",
+    };
+    return `${JSON.stringify(log, null, 2)}\n`;
+}
+function formatRule(action) {
+    return {
+        fullDescription: { text: action.detail },
+        help: { text: action.detail },
+        id: action.id,
+        name: action.title,
+        shortDescription: { text: action.title },
+    };
+}
+function formatResult(action) {
+    return {
+        level: sarifLevel(action.priority),
+        locations: [
+            {
+                physicalLocation: {
+                    artifactLocation: {
+                        uri: artifactUriForAction(action.id),
+                        uriBaseId: SOURCE_ROOT_URI_BASE_ID,
+                    },
+                    region: {
+                        startLine: 1,
+                    },
+                },
+            },
+        ],
+        message: { text: `${action.title}: ${action.detail}` },
+        ruleId: action.id,
+    };
+}
+function sarifLevel(priority) {
+    switch (priority) {
+        case "high":
+            return "error";
+        case "medium":
+            return "warning";
+        case "low":
+            return "note";
+        default:
+            return assertNever(priority);
+    }
+}
+function rootUri(root) {
+    const uri = pathToFileURL(root).href;
+    return uri.endsWith("/") ? uri : `${uri}/`;
+}
+function assertNever(value) {
+    throw new Error(`unexpected SARIF value: ${value}`);
+}
+//# sourceMappingURL=sarif.js.map

package/dist/sarif.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sarif.js","sourceRoot":"","sources":["../src/sarif.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAsD5D,MAAM,uBAAuB,GAAG,WAAW,CAAA;AAE3C,MAAM,UAAU,WAAW,CAAC,MAAmB;IAC7C,MAAM,GAAG,GAAa;QACpB,OAAO,EAAE,+CAA+C;QACxD,IAAI,EAAE;YACJ;gBACE,kBAAkB,EAAE;oBAClB,CAAC,uBAAuB,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE;iBACzD;gBACD,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;gBACzC,IAAI,EAAE;oBACJ,MAAM,EAAE;wBACN,IAAI,EAAE,WAAW;wBACjB,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;wBACrC,eAAe,EAAE,OAAO;qBACzB;iBACF;aACF;SACF;QACD,OAAO,EAAE,OAAO;KACjB,CAAA;IAED,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAA;AAC5C,CAAC;AAED,SAAS,UAAU,CAAC,MAAmB;IACrC,OAAO;QACL,eAAe,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE;QACxC,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE;QAC7B,EAAE,EAAE,MAAM,CAAC,EAAE;QACb,IAAI,EAAE,MAAM,CAAC,KAAK;QAClB,gBAAgB,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,EAAE;KACzC,CAAA;AACH,CAAC;AAED,SAAS,YAAY,CAAC,MAAmB;IACvC,OAAO;QACL,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC;QAClC,SAAS,EAAE;YACT;gBACE,gBAAgB,EAAE;oBAChB,gBAAgB,EAAE;wBAChB,GAAG,EAAE,oBAAoB,CAAC,MAAM,CAAC,EAAE,CAAC;wBACpC,SAAS,EAAE,uBAAuB;qBACnC;oBACD,MAAM,EAAE;wBACN,SAAS,EAAE,CAAC;qBACb;iBACF;aACF;SACF;QACD,OAAO,EAAE,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,KAAK,KAAK,MAAM,CAAC,MAAM,EAAE,EAAE;QACtD,MAAM,EAAE,MAAM,CAAC,EAAE;KAClB,CAAA;AACH,CAAC;AAED,SAAS,UAAU,CAAC,QAAiC;IACnD,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,MAAM;YACT,OAAO,OAAO,CAAA;QAChB,KAAK,QAAQ;YACX,OAAO,SAAS,CAAA;QAClB,KAAK,KAAK;YACR,OAAO,MAAM,CAAA;QACf;YACE,OAAO,WAAW,CAAC,QAAQ,CAAC,CAAA;IAChC,CAAC;AACH,CAAC;AAED,SAAS,OAAO,CAAC,IAAY;IAC3B,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,IAAI,CAAA;IACpC,OAAO,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,CAAA;AAC5C,CAAC;AAED,SAAS,WAAW,CAAC,KAAY;IAC/B,MAAM,IAAI,KAAK,CAAC,2BAA2B,KAAK,EAAE,CAAC,CAAA;AACrD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+export declare const REPORT_STATUSES: readonly ["ready", "needs-work"];
+export type ReportStatus = (typeof REPORT_STATUSES)[number];
+export declare const OUTPUT_FORMATS: readonly ["json", "markdown", "release-notes", "contributor-onboarding", "triage-suggestions", "sarif", "github-annotations"];
+export type OutputFormat = (typeof OUTPUT_FORMATS)[number];
+export type MaintainerFiles = {
+    readonly changelog: boolean;
+    readonly codeOfConduct: boolean;
+    readonly contributing: boolean;
+    readonly funding: boolean;
+    readonly goodFirstIssueTemplate: boolean;
+    readonly issueTemplate: boolean;
+    readonly license: boolean;
+    readonly pullRequestTemplate: boolean;
+    readonly readme: boolean;
+    readonly releaseWorkflow: boolean;
+    readonly security: boolean;
+    readonly workflowCount: number;
+};
+export type RepositorySignals = {
+    readonly branch: string;
+    readonly commitsLast30Days: number;
+    readonly contributorsLast90Days: number;
+    readonly files: MaintainerFiles;
+    readonly latestCommitIso: string | null;
+    readonly root: string;
+};
+export type CheckId = "readme" | "license" | "contributing" | "issue-template" | "good-first-issue-template" | "pull-request-template" | "security" | "ci-workflow" | "release-workflow" | "changelog" | "funding" | "external-contributors" | "code-of-conduct" | "recent-activity";
+export type ActionId = "add-readme" | "add-license" | "add-contributing-guide" | "add-issue-template" | "add-good-first-issue-template" | "add-pull-request-template" | "add-security-policy" | "add-ci-workflow" | "add-release-workflow" | "add-changelog" | "add-funding" | "invite-contributors" | "add-code-of-conduct" | "resume-maintenance";
+export type PulseCheck = {
+    readonly detail: string;
+    readonly id: CheckId;
+    readonly label: string;
+    readonly passed: boolean;
+    readonly points: number;
+};
+export type PulseAction = {
+    readonly detail: string;
+    readonly id: ActionId;
+    readonly priority: "high" | "medium" | "low";
+    readonly title: string;
+};
+export type PulseReport = {
+    readonly actions: readonly PulseAction[];
+    readonly branch: string;
+    readonly checks: readonly PulseCheck[];
+    readonly generatedAtIso: string;
+    readonly latestCommitIso: string | null;
+    readonly root: string;
+    readonly score: number;
+    readonly status: ReportStatus;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,11 @@
+export const REPORT_STATUSES = ["ready", "needs-work"];
+export const OUTPUT_FORMATS = [
+    "json",
+    "markdown",
+    "release-notes",
+    "contributor-onboarding",
+    "triage-suggestions",
+    "sarif",
+    "github-annotations",
+];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,YAAY,CAAU,CAAA;AAG/D,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,MAAM;IACN,UAAU;IACV,eAAe;IACf,wBAAwB;IACxB,oBAAoB;IACpB,OAAO;IACP,oBAAoB;CACZ,CAAA"}

package/docs/CLAUDE_FOR_OSS_PLAYBOOK.md

@@ -0,0 +1,31 @@
+# Claude for Open Source Playbook
+
+The goal is to become eligible through visible open source maintenance work, not a one-off application.
+
+## Positioning
+
+`oss-pulse` helps maintainers make contribution paths visible and measurable. That directly supports the open source ecosystem and gives the project a clear story when applying for Claude for Open Source.
+
+## 90-Day Targets
+
+- ship a usable CLI and GitHub Action
+- publish to npm
+- merge at least 20 external contributor pull requests
+- land useful pull requests in external open source repositories
+- document real repository scans and before-after fixes
+
+## Weekly Operating Rhythm
+
+- Monday: choose 3 small external OSS contributions
+- Tuesday: ship one `oss-pulse` improvement
+- Wednesday: write or refine good first issues
+- Thursday: review contributor pull requests
+- Friday: publish a short changelog and usage note
+
+## Application Evidence
+
+- merged external pull requests authored by us
+- external contributors merged into this project
+- npm downloads and GitHub stars
+- public examples where `oss-pulse` improved a repo
+- consistent release history

package/docs/CONTRIBUTOR_BACKLOG.md

@@ -0,0 +1,93 @@
+# Contributor Backlog
+
+This backlog is designed to help outside contributors land small pull requests quickly.
+
+## Good First Issues
+
+Starter issues are clear for the current release. Add the next batch from the roadmap.
+
+## Shipped
+
+1. Add `--fail-under <score>` for CI.
+   - Shipped in `0.1.0`.
+   - The CLI exits `1` when score is below the threshold and `0` otherwise.
+
+2. Add `--summary-only` Markdown output.
+   - Shipped in `0.1.0`.
+   - The output includes score and next actions without the full checks table.
+
+3. Add `CHANGELOG.md` detection to the maintainer file checks.
+   - Shipped in `0.1.0`.
+   - A repository with `CHANGELOG.md` gets a passing changelog check.
+
+4. Add `FUNDING.yml` detection.
+   - Shipped in `0.1.0`.
+   - `.github/FUNDING.yml` appears in the JSON checks.
+
+5. Add release workflow detection.
+   - Shipped in `0.1.0`.
+   - Acceptance: repositories with `.github/workflows/release.yml` receive a release-readiness check.
+
+6. Improve unsupported format errors.
+   - Shipped in `0.1.0`.
+   - `--format xml` suggests the accepted output formats.
+
+7. Add feature request examples to the README.
+   - Shipped in `0.1.0`.
+   - README shows one CLI use case and one GitHub Action use case.
+
+8. Add JSON schema documentation.
+   - Shipped in `0.1.0`.
+   - `docs/REPORT_SCHEMA.md` describes every report field and example values.
+
+9. Add fixture-based integration tests.
+   - Shipped in `0.1.0`.
+   - Test fixtures cover a complete repo, a sparse repo, and a nested package path.
+
+10. Add real repository case studies.
+    - Shipped in `0.1.0`.
+    - `docs/examples/` contains before-after reports for two public repos.
+
+11. Add good first issue template detection.
+    - Shipped in `0.1.0`.
+    - Repositories with `.github/ISSUE_TEMPLATE/good_first_issue.md` receive starter contribution readiness points.
+
+12. Add release notes draft output.
+    - Shipped in `0.1.0`.
+    - `--format release-notes` emits a paste-ready Markdown draft with score, verified surfaces, and follow-up actions.
+
+13. Add contributor onboarding report.
+    - Shipped in `0.1.0`.
+    - `--format contributor-onboarding` emits available surfaces, maintainer follow-up actions, and a first PR checklist.
+
+14. Add issue and pull request triage suggestions.
+    - Shipped in `0.1.0`.
+    - `--format triage-suggestions` emits issue triage and pull request review guidance.
+
+15. Harden GitHub Action metadata and README usage.
+    - Shipped in `0.1.0`.
+    - `action.yml` documents every supported output format and README lists Action inputs.
+
+16. Add SARIF output.
+    - Shipped in `0.1.0`.
+    - `--format sarif` emits SARIF 2.1.0 results for missing maintainer surfaces.
+
+17. Add GitHub workflow annotations.
+    - Shipped in `0.1.0`.
+    - `--format github-annotations` emits `::error`, `::warning`, and `::notice` commands for GitHub Actions.
+
+18. Add machine-readable JSON Schema documentation.
+    - Shipped in `0.1.0`.
+    - `docs/report.schema.json` describes `--format json` output and is tested against runtime ids.
+
+## Help Wanted
+
+Help wanted issues are clear for the current release. Add the next batch from the roadmap.
+
+## Maintainer Routine
+
+- Keep issues under one focused behavior.
+- Label starter issues with `good first issue`.
+- Ask contributors to include the command they ran.
+- Prefer small pull requests over broad refactors.
+- Close stale ideas gently and point to the roadmap.

package/docs/RELEASE.md

@@ -0,0 +1,38 @@
+# Release
+
+This project publishes two surfaces:
+
+- npm package: `oss-pulse`
+- GitHub composite Action: pinned repository tags such as `v0.1.0`
+
+## Prerequisites
+
+- npm package name is available or owned by the maintainer.
+- GitHub repository has `NPM_TOKEN` configured as an Actions secret.
+- The release branch passes `npm run check`.
+
+## Local Preflight
+
+```bash
+npm ci
+npm run check
+npm run build
+npm pack --dry-run
+```
+
+Confirm the dry-run includes `dist`, `README.md`, `CHANGELOG.md`, `LICENSE`, `action.yml`, and `package.json`.
+
+## Publish
+
+1. Update `CHANGELOG.md`.
+2. Update `package.json` version.
+3. Run the local preflight.
+4. Create and push a tag named `vX.Y.Z`.
+5. Create a GitHub Release from that tag.
+6. The `Release` workflow publishes to npm with provenance.
+
+## After Publish
+
+- Run `npx --yes oss-pulse@X.Y.Z scan . --format markdown`.
+- Open a pull request that uses the pinned Action tag.
+- Add one real scan example to the README or `docs/examples/`.

package/docs/REPORT_SCHEMA.md

@@ -0,0 +1,116 @@
+# Report Schema
+
+`oss-pulse scan --format json` emits one JSON object followed by a newline.
+
+The schema is intended for CI jobs, dashboards, and repository automation that need a stable maintainer-readiness signal.
+
+The machine-readable JSON Schema lives at [`docs/report.schema.json`](./report.schema.json). It is tested against the runtime check and action identifiers so automation consumers do not drift from CLI output.
+
+For code scanning consumers, `oss-pulse scan --format sarif` emits a SARIF 2.1.0 log where each remediation action is represented as a SARIF result.
+
+For GitHub Actions consumers, `oss-pulse scan --format github-annotations` emits workflow commands where high-priority actions become errors, medium-priority actions become warnings, and low-priority actions become notices.
+
+## Top-Level Object
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `actions` | `PulseAction[]` | Ranked remediation actions for failed checks. Empty when `status` is `ready`. |
+| `branch` | `string` | Current git branch, or `detached` when no branch name is available. |
+| `checks` | `PulseCheck[]` | Every scored maintainer-readiness check in display order. |
+| `generatedAtIso` | `string` | ISO timestamp for when the report was generated. |
+| `latestCommitIso` | `string \| null` | ISO timestamp for the latest commit, or `null` when unavailable. |
+| `root` | `string` | Absolute path to the scanned git repository root. |
+| `score` | `number` | Integer score from `0` to `100`. |
+| `status` | `"ready" \| "needs-work"` | `ready` only when `score` is `100`. |
+
+## PulseCheck
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `detail` | `string` | Human-readable check detail. |
+| `id` | `CheckId` | Stable machine-readable check id. |
+| `label` | `string` | Short display label. |
+| `passed` | `boolean` | Whether the check passed. |
+| `points` | `number` | Awarded points. Failed checks always emit `0`. |
+
+## CheckId Values
+
+| ID | Max Points |
+| --- | ---: |
+| `readme` | 10 |
+| `license` | 15 |
+| `contributing` | 10 |
+| `issue-template` | 5 |
+| `good-first-issue-template` | 5 |
+| `pull-request-template` | 10 |
+| `security` | 10 |
+| `ci-workflow` | 5 |
+| `release-workflow` | 5 |
+| `changelog` | 5 |
+| `funding` | 5 |
+| `external-contributors` | 5 |
+| `code-of-conduct` | 5 |
+| `recent-activity` | 5 |
+
+## PulseAction
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `detail` | `string` | Human-readable remediation detail. |
+| `id` | `ActionId` | Stable machine-readable action id. |
+| `priority` | `"high" \| "medium" \| "low"` | Suggested action priority. |
+| `title` | `string` | Short display title. |
+
+## ActionId Values
+
+- `add-readme`
+- `add-license`
+- `add-contributing-guide`
+- `add-issue-template`
+- `add-good-first-issue-template`
+- `add-pull-request-template`
+- `add-security-policy`
+- `add-ci-workflow`
+- `add-release-workflow`
+- `add-changelog`
+- `add-funding`
+- `invite-contributors`
+- `add-code-of-conduct`
+- `resume-maintenance`
+
+## Example
+
+```json
+{
+  "actions": [
+    {
+      "detail": "Add .github/FUNDING.yml so sponsor paths are discoverable from GitHub.",
+      "id": "add-funding",
+      "priority": "low",
+      "title": "Add funding metadata"
+    }
+  ],
+  "branch": "main",
+  "checks": [
+    {
+      "detail": "README found",
+      "id": "readme",
+      "label": "README",
+      "passed": true,
+      "points": 10
+    },
+    {
+      "detail": "No funding metadata",
+      "id": "funding",
+      "label": "Funding metadata",
+      "passed": false,
+      "points": 0
+    }
+  ],
+  "generatedAtIso": "2026-07-08T06:30:37.183Z",
+  "latestCommitIso": null,
+  "root": "/path/to/repository",
+  "score": 85,
+  "status": "needs-work"
+}
+```

package/docs/ROADMAP.md

@@ -0,0 +1,30 @@
+# Roadmap
+
+`oss-pulse` should stay small enough for maintainers to trust, but useful enough that real projects run it in CI.
+
+## 0.1.x
+
+- keep the repository health report stable
+- ship and harden `--fail-under <score>` for CI gates
+- ship and harden `--summary-only` for compact GitHub summaries
+- ship and harden detector coverage for funding, changelog, and release workflow files
+- ship and harden good-first-issue template detection
+- ship and harden release notes draft output
+- ship and harden contributor onboarding output
+- ship and harden issue and pull request triage suggestions
+- ship and harden SARIF output for code scanning integrations
+- ship and harden GitHub workflow annotations for CI surfaces
+- ship and harden error messages and GitHub Action documentation
+- ship and harden JSON Schema documentation for report consumers
+- add examples from real open source repositories
+- keep contributor-facing issues small and reviewable
+
+## 0.2.0
+
+- publish a repository Action tag after npm publication
+
+## Later
+
+- support hosted GitHub repository scans
+- provide a web report renderer
+- collect anonymized benchmark examples only with explicit opt-in

package/docs/examples/README.md

@@ -0,0 +1,12 @@
+# Example Reports
+
+These examples show `oss-pulse` against public repositories, then a local what-if scan after adding the recommended maintainer surfaces in a temporary clone.
+
+The after reports are not claims about upstream repository state. They show what the score would look like if the listed maintenance files and recent contributor activity were added.
+
+Generated on 2026-07-08.
+
+## Examples
+
+- [octocat/Hello-World](octocat-hello-world.md)
+- [sindresorhus/is](sindresorhus-is.md)

package/docs/examples/octocat-hello-world.md

@@ -0,0 +1,44 @@
+# octocat/Hello-World Case Study
+
+Repository: https://github.com/octocat/Hello-World
+
+Generated on 2026-07-08 from a shallow local clone.
+
+## Before
+
+```text
+Score: 10/100
+Status: needs-work
+Branch: master
+Latest commit: 2012-03-06T15:06:50-08:00
+```
+
+Passing checks:
+
+- README
+
+First recommended actions:
+
+1. Add LICENSE
+2. Add CONTRIBUTING guide
+3. Add issue template
+4. Add good first issue template
+5. Add pull request template
+
+## Local What-If After
+
+The temporary clone received:
+
+- LICENSE, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, CHANGELOG
+- issue, good first issue, and pull request templates
+- CI and release workflows
+- funding metadata
+- two recent commits from two authors
+
+```text
+Score: 100/100
+Status: ready
+Next actions: none
+```
+
+This demonstrates the smallest maintenance-surface path from a demonstration repository to a fully passing `oss-pulse` report.

package/docs/examples/sindresorhus-is.md

@@ -0,0 +1,47 @@
+# sindresorhus/is Case Study
+
+Repository: https://github.com/sindresorhus/is
+
+Generated on 2026-07-08 from a shallow local clone.
+
+## Before
+
+```text
+Score: 40/100
+Status: needs-work
+Branch: main
+Latest commit: 2026-05-11T22:57:22+09:00
+```
+
+Passing checks:
+
+- README
+- License
+- Security policy
+- CI workflow
+
+First recommended actions:
+
+1. Add CONTRIBUTING guide
+2. Add issue template
+3. Add good first issue template
+4. Add pull request template
+5. Add release workflow
+
+## Local What-If After
+
+The temporary clone received:
+
+- CONTRIBUTING, CODE_OF_CONDUCT, CHANGELOG
+- issue, good first issue, and pull request templates
+- release workflow
+- funding metadata
+- two recent commits from two authors
+
+```text
+Score: 100/100
+Status: ready
+Next actions: none
+```
+
+This demonstrates how an already mature package can use `oss-pulse` to find smaller contributor-onboarding gaps.