oss-signal 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.0
+
+- Added direct GitHub repository audits for public repositories.
+- Added `owner/repo` shorthand and `--ref` support.
+- Added GitHub community profile evidence for shared maintainer files.
+- Added a zero-dependency GitHub Action wrapper with score outputs.
+- Updated the CLI help output and package metadata for npm 11.
+
 ## 0.1.0
 
 - Initial CLI with Markdown and JSON output.

package/README.md

@@ -21,6 +21,7 @@ Open-source projects often fail quietly because the maintainer workflow is undoc
 - Contributors can attach a report to a cleanup issue or pull request.
 - Teams can gate release readiness with `--fail-under`.
 - Foundations and working groups can compare repository hygiene across many projects.
+- CI maintainers can add it as a GitHub Action and publish the report as an artifact.
 
 ## Install
 
@@ -45,6 +46,13 @@ Audit the current directory:
 oss-signal
 ```
 
+Audit a public GitHub repository without cloning it:
+
+```bash
+oss-signal https://github.com/SalmonPlays/oss-signal
+oss-signal platformatic/massimo --format json
+```
+
 Write a Markdown report:
 
 ```bash
@@ -73,6 +81,8 @@ oss-signal . --format markdown --output docs/maintainer-readiness.md
 
 See [docs/rules.md](docs/rules.md) for rule details and scoring weights.
 
+For GitHub URL audits, `oss-signal` reads the repository file tree through the GitHub API and also uses GitHub's community profile signal when available. This lets it detect organization-level files such as a shared code of conduct.
+
 ## Real Output
 
 This repository audits itself at **100/100 (A)**:
@@ -86,7 +96,7 @@ Summary:
 - Total checks: 15
 ```
 
-See [docs/self-audit.md](docs/self-audit.md) for the full self-audit report.
+See [docs/self-audit.md](docs/self-audit.md) for the full local self-audit report and [docs/examples/github-url-report.md](docs/examples/github-url-report.md) for the GitHub URL audit output.
 
 ## Field Audits
 
@@ -98,6 +108,8 @@ See [docs/self-audit.md](docs/self-audit.md) for the full self-audit report.
 
 See [docs/outreach](docs/outreach) for the reports and draft issue text. Drafts are not posted automatically; maintainers should only receive specific, useful, and respectful suggestions.
 
+For a compact maintainer/adoption summary, see [docs/adoption-evidence.md](docs/adoption-evidence.md).
+
 ## Example Recommendation Output
 
 ```text
@@ -120,12 +132,17 @@ When `--fail-under <score>` is provided, it exits with `1` if the score is below
 oss-signal . --fail-under 80
 ```
 
-## CI
+## GitHub Action
 
-Add this to a GitHub Actions workflow:
+Add `oss-signal` directly to a GitHub Actions workflow:
 
 ```yaml
-- run: npx oss-signal . --fail-under 80
+- uses: SalmonPlays/oss-signal@v0.2.0
+  id: oss-signal
+  with:
+    fail-under: "80"
+    output: oss-signal-report.md
+- run: echo "score ${{ steps.oss-signal.outputs.score }} (${{ steps.oss-signal.outputs.grade }})"
 ```
 
 Full workflow example:
@@ -143,25 +160,33 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: SalmonPlays/oss-signal@v0.2.0
+        id: oss-signal
         with:
-          node-version: 22
-      - run: npx oss-signal . --format markdown --output oss-signal-report.md --fail-under 80
+          fail-under: "80"
+          output: oss-signal-report.md
       - uses: actions/upload-artifact@v4
         with:
           name: oss-signal-report
           path: oss-signal-report.md
 ```
 
+See [docs/examples/github-action-workflow.yml](docs/examples/github-action-workflow.yml) for a copyable workflow.
+
+You can also run the CLI directly in CI:
+
+```yaml
+- run: npx oss-signal . --format markdown --output oss-signal-report.md --fail-under 80
+```
+
 ## Current Limitations
 
-- It inspects local files only; GitHub URL mode is on the roadmap.
-- It checks deterministic maintenance signals, not code quality.
+- It checks deterministic maintenance signals, not code quality or project importance.
+- GitHub URL mode uses unauthenticated API requests unless `GITHUB_TOKEN` is set, so very heavy usage may hit GitHub rate limits.
 - A high score does not prove a project is important. It proves the maintainer workflow is documented and automatable.
 
 ## Roadmap
 
-- GitHub API mode for public repository URLs
 - Ecosystem-specific profiles for Python, Rust, Go, and JavaScript packages
 - SARIF output for code scanning dashboards
 - Rules for release automation and provenance metadata

package/action.yml

@@ -0,0 +1,41 @@
+name: oss-signal
+description: Audit open-source repository maintenance readiness and produce actionable maintainer next steps.
+author: SalmonPlays
+branding:
+  icon: activity
+  color: blue
+inputs:
+  path:
+    description: Local repository path, GitHub URL, or owner/repo shorthand to audit.
+    required: false
+    default: "."
+  format:
+    description: Output format, either markdown or json.
+    required: false
+    default: markdown
+  output:
+    description: Report file path.
+    required: false
+    default: oss-signal-report.md
+  fail-under:
+    description: Fail the action when the score is below this number.
+    required: false
+  max-files:
+    description: Maximum files to inspect.
+    required: false
+    default: "20000"
+  ref:
+    description: Git ref for GitHub URL audits.
+    required: false
+outputs:
+  score:
+    description: Numeric maintainer-readiness score.
+  grade:
+    description: Letter grade for the maintainer-readiness score.
+  failed:
+    description: Number of failed checks.
+  report-path:
+    description: Path to the generated report file, when output is enabled.
+runs:
+  using: node20
+  main: src/action.js

package/docs/adoption-evidence.md

@@ -0,0 +1,58 @@
+# Adoption Evidence
+
+This page collects the public evidence that `oss-signal` is built for real open-source maintainer workflows.
+
+## Project Links
+
+- Repository: https://github.com/SalmonPlays/oss-signal
+- npm package: https://www.npmjs.com/package/oss-signal
+- GitHub Action tag: https://github.com/SalmonPlays/oss-signal/tree/v0.2.0
+- GitHub Action metadata: [action.yml](../action.yml)
+- Self-audit report: [docs/self-audit.md](self-audit.md)
+- GitHub URL audit report: [docs/examples/github-url-report.md](examples/github-url-report.md)
+- GitHub Action workflow example: [docs/examples/github-action-workflow.yml](examples/github-action-workflow.yml)
+- Rule reference: [docs/rules.md](rules.md)
+
+## Maintainer Use Case
+
+`oss-signal` audits repository maintenance readiness and returns a score with concrete next steps. It is aimed at work maintainers actually do: documenting contribution paths, setting support boundaries, keeping CI visible, collecting useful issue context, and making security reporting easier.
+
+The CLI supports two practical modes:
+
+- Local repository audit for maintainers working in a clone.
+- Public GitHub repository audit for quick triage without cloning.
+
+It also ships as a GitHub Action, so maintainers can gate repository hygiene in CI and upload a Markdown report as a workflow artifact.
+
+## Public Field Audits
+
+The tool has been used to generate maintainer-readiness reports for public repositories and convert them into respectful cleanup issues:
+
+| Repository | Report | Posted issue |
+| --- | --- | --- |
+| `platformatic/massimo` | [report](outreach/platformatic-massimo-report.md) | https://github.com/platformatic/massimo/issues/159 |
+| `supermarkt/checkjebon` | [report](outreach/supermarkt-checkjebon-report.md) | https://github.com/supermarkt/checkjebon/issues/22 |
+| `sammorrisdesign/interactive-feed` | [report](outreach/sammorrisdesign-interactive-feed-report.md) | https://github.com/sammorrisdesign/interactive-feed/issues/14 |
+
+These issues are evidence of the intended maintainer workflow: run a deterministic audit, explain the missing signals, and give maintainers a small set of actionable improvements.
+
+## Verification Commands
+
+From this repository:
+
+```bash
+npm run check
+npm run audit:github
+node src/cli.js platformatic/massimo --format json
+```
+
+The current repository self-audit score is 100/100, the GitHub community profile health score is 100, and CI verifies the local GitHub Action wrapper.
+
+Public CI evidence:
+
+- GitHub Action self-test job: https://github.com/SalmonPlays/oss-signal/actions/runs/26801682014/job/79009525705
+- CodeQL run: https://github.com/SalmonPlays/oss-signal/actions/runs/26801681976
+
+## Boundaries
+
+`oss-signal` does not claim that a repository is high quality or widely adopted. It measures maintainability signals that are visible in repository files and GitHub community profile metadata.

package/docs/examples/github-action-workflow.yml

@@ -0,0 +1,22 @@
+name: Repository health
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  oss-signal:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: SalmonPlays/oss-signal@v0.2.0
+        id: oss-signal
+        with:
+          fail-under: "80"
+          output: oss-signal-report.md
+      - uses: actions/upload-artifact@v4
+        with:
+          name: oss-signal-report
+          path: oss-signal-report.md
+      - run: echo "oss-signal score ${{ steps.oss-signal.outputs.score }} (${{ steps.oss-signal.outputs.grade }})"

package/docs/examples/github-url-report.md

@@ -0,0 +1,41 @@
+# OSS Signal Report
+
+Repository: `https://github.com/SalmonPlays/oss-signal`
+Source: GitHub (SalmonPlays/oss-signal@main)
+Generated: 2026-06-02T06:02:52.844Z
+
+Score: **100/100** (A)
+
+## Summary
+
+- Passed: 15
+- Failed: 0
+- Total checks: 15
+- Default branch: main
+- GitHub stars: 0
+- GitHub community health: 100
+
+## Checks
+
+| Status | Check | Why it matters |
+| --- | --- | --- |
+| PASS | README | A clear README is the front door for users and contributors. |
+| PASS | License | A license tells downstream users what they may legally do with the code. |
+| PASS | Contributing guide | Maintainers get better issues and pull requests when expectations are documented. |
+| PASS | Security policy | Responsible disclosure needs a private, documented path. |
+| PASS | Code of conduct | Community norms reduce ambiguity during difficult interactions. |
+| PASS | Changelog | Users need a durable place to understand release impact. |
+| PASS | Support policy | Support boundaries help maintainers avoid turning every request into unpaid consulting. |
+| PASS | Continuous integration | CI catches regressions before maintainers merge changes. |
+| PASS | Tests | Tests make review safer and lower the cost of outside contributions. |
+| PASS | Issue templates | Issue templates collect the facts maintainers need to reproduce and triage. |
+| PASS | Pull request template | PR templates nudge contributors to include tests, docs, and review context. |
+| PASS | Dependency update automation | Automated dependency updates reduce security and compatibility drift. |
+| PASS | Static security analysis | Static analysis finds common vulnerability patterns before releases. |
+| PASS | Node package metadata | Package metadata makes installation, testing, and release automation discoverable. |
+| PASS | Dependency lockfile | Lockfiles make CI and contributor setup reproducible. |
+
+## Recommended Next Steps
+
+No missing checks. Keep the report current as the repository evolves.
+

package/docs/self-audit.md

@@ -1,7 +1,8 @@
 # OSS Signal Report
 
 Repository: `/Users/amon/Documents/Codex/2026-06-01/openai-s/outputs/oss-signal`
-Generated: 2026-06-02T01:40:56.294Z
+Source: local
+Generated: 2026-06-02T06:02:50.825Z
 
 Score: **100/100** (A)
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "oss-signal",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A dependency-light CLI that audits open-source repository maintenance readiness.",
   "type": "module",
   "bin": {
-    "oss-signal": "./src/cli.js"
+    "oss-signal": "src/cli.js"
   },
   "repository": {
     "type": "git",
@@ -17,6 +17,7 @@
   "files": [
     "src",
     "docs",
+    "action.yml",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -25,6 +26,7 @@
     "test": "node --test",
     "lint": "node --check src/*.js test/*.test.js",
     "audit:self": "node src/cli.js . --format markdown --output docs/self-audit.md",
+    "audit:github": "node src/cli.js SalmonPlays/oss-signal --format markdown --output docs/examples/github-url-report.md",
     "audit:check": "node src/cli.js . --format json --fail-under 100 > /dev/null",
     "check": "npm run lint && npm test && npm run audit:check",
     "prepublishOnly": "npm run check"

package/src/action.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { auditTarget, renderMarkdown } from "./index.js";
+
+const OUTPUT_DELIMITER = "oss_signal_output";
+
+export async function runAction(env = process.env, stdout = process.stdout, stderr = process.stderr) {
+  const options = parseActionInputs(env);
+  const report = await auditTarget(options.path, {
+    maxFiles: options.maxFiles,
+    ref: options.ref
+  });
+  const body = options.format === "json" ? `${JSON.stringify(report, null, 2)}\n` : renderMarkdown(report);
+
+  if (options.output) {
+    await fs.mkdir(path.dirname(path.resolve(options.output)), { recursive: true });
+    await fs.writeFile(options.output, body, "utf8");
+  } else {
+    stdout.write(body);
+  }
+
+  await writeGitHubOutput(env.GITHUB_OUTPUT, {
+    score: report.score,
+    grade: report.grade,
+    failed: report.summary.failed,
+    "report-path": options.output ?? ""
+  });
+
+  if (typeof options.failUnder === "number" && report.score < options.failUnder) {
+    stderr.write(`oss-signal: score ${report.score} is below fail-under ${options.failUnder}\n`);
+    process.exitCode = 1;
+  }
+
+  return report;
+}
+
+export function parseActionInputs(env = process.env) {
+  const format = getInput(env, "format") || "markdown";
+  if (!["markdown", "json"].includes(format)) {
+    throw new Error("format must be either markdown or json");
+  }
+
+  return {
+    path: getInput(env, "path") || ".",
+    format,
+    output: emptyToUndefined(getInput(env, "output")) ?? "oss-signal-report.md",
+    failUnder: parseOptionalNumber(getInput(env, "fail-under"), "fail-under"),
+    maxFiles: parseOptionalNumber(getInput(env, "max-files"), "max-files") ?? 20000,
+    ref: emptyToUndefined(getInput(env, "ref"))
+  };
+}
+
+export async function writeGitHubOutput(outputFile, values) {
+  if (!outputFile) {
+    return;
+  }
+
+  const body = Object.entries(values)
+    .map(([name, value]) => `${name}<<${OUTPUT_DELIMITER}\n${value}\n${OUTPUT_DELIMITER}`)
+    .join("\n");
+  await fs.appendFile(outputFile, `${body}\n`, "utf8");
+}
+
+function getInput(env, name) {
+  const directKey = `INPUT_${name.toUpperCase()}`;
+  const normalizedKey = `INPUT_${name.toUpperCase().replaceAll("-", "_")}`;
+  return env[directKey]?.trim() || env[normalizedKey]?.trim() || "";
+}
+
+function parseOptionalNumber(value, name) {
+  const normalized = emptyToUndefined(value);
+  if (normalized === undefined) {
+    return undefined;
+  }
+
+  const parsed = Number(normalized);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`${name} must be a number`);
+  }
+  return parsed;
+}
+
+function emptyToUndefined(value) {
+  return value === undefined || value === "" ? undefined : value;
+}
+
+function escapeWorkflowCommand(value) {
+  return String(value).replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
+}
+
+function isMainModule() {
+  return process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+}
+
+if (isMainModule()) {
+  runAction().catch((error) => {
+    process.stdout.write(`::error::${escapeWorkflowCommand(error.message)}\n`);
+    process.exitCode = 1;
+  });
+}

package/src/cli.js

@@ -1,8 +1,6 @@
 #!/usr/bin/env node
 import { promises as fs } from "node:fs";
-import { auditRepository, renderMarkdown } from "./index.js";
-
-const VERSION = "0.1.0";
+import { auditTarget, renderMarkdown, VERSION } from "./index.js";
 
 async function main(argv) {
   const options = parseArgs(argv);
@@ -16,7 +14,10 @@ async function main(argv) {
     return;
   }
 
-  const report = await auditRepository(options.path, { maxFiles: options.maxFiles });
+  const report = await auditTarget(options.path, {
+    maxFiles: options.maxFiles,
+    ref: options.ref
+  });
   const body = options.format === "json" ? `${JSON.stringify(report, null, 2)}\n` : renderMarkdown(report);
 
   if (options.output) {
@@ -38,6 +39,7 @@ function parseArgs(argv) {
     output: undefined,
     failUnder: undefined,
     maxFiles: 20000,
+    ref: undefined,
     help: false,
     version: false
   };
@@ -66,6 +68,10 @@ function parseArgs(argv) {
       options.maxFiles = parseNumber(requireValue(argv, ++index, "--max-files"), "--max-files");
     } else if (arg.startsWith("--max-files=")) {
       options.maxFiles = parseNumber(arg.slice("--max-files=".length), "--max-files");
+    } else if (arg === "--ref") {
+      options.ref = requireValue(argv, ++index, "--ref");
+    } else if (arg.startsWith("--ref=")) {
+      options.ref = arg.slice("--ref=".length);
     } else if (arg.startsWith("-")) {
       throw new Error(`Unknown option: ${arg}`);
     } else {
@@ -105,13 +111,19 @@ function helpText() {
   return `oss-signal audits open-source repository maintenance readiness.
 
 Usage:
-  oss-signal [path] [--format markdown|json] [--output file] [--fail-under score]
+  oss-signal [path-or-github-url] [--format markdown|json] [--output file] [--fail-under score]
+
+Examples:
+  oss-signal .
+  oss-signal https://github.com/SalmonPlays/oss-signal
+  oss-signal platformatic/massimo --format json
 
 Options:
   --format       Output format. Defaults to markdown.
   --output, -o   Write the report to a file instead of stdout.
   --fail-under   Exit with code 1 when the score is below this value.
   --max-files    Maximum files to inspect. Defaults to 20000.
+  --ref          Git ref for GitHub URL audits. Defaults to the repository default branch.
   --version, -v  Show the CLI version.
   --help, -h     Show this help message.
 `;

package/src/index.js

@@ -1,6 +1,9 @@
 import { promises as fs } from "node:fs";
+import https from "node:https";
 import path from "node:path";
 
+export const VERSION = "0.2.0";
+
 const COMMUNITY_FILES = [
   {
     id: "readme",
@@ -146,12 +149,61 @@ const DEFAULT_IGNORE_DIRS = new Set([
 export async function auditRepository(root, options = {}) {
   const absoluteRoot = path.resolve(root ?? ".");
   const tree = await listRepositoryFiles(absoluteRoot, options);
+  return createReportFromTree(tree, {
+    root: absoluteRoot,
+    source: {
+      type: "local",
+      location: absoluteRoot
+    }
+  });
+}
+
+export async function auditTarget(target = ".", options = {}) {
+  const normalizedTarget = target ?? ".";
+  if (!isGitHubUrl(normalizedTarget) && await pathExists(normalizedTarget)) {
+    return auditRepository(normalizedTarget, options);
+  }
+  if (isGitHubTarget(normalizedTarget)) {
+    return auditGitHubRepository(normalizedTarget, options);
+  }
+  return auditRepository(normalizedTarget, options);
+}
+
+export async function auditGitHubRepository(target, options = {}) {
+  const parsed = parseGitHubTarget(target);
+  const fetchImpl = options.fetchImpl;
+  const headers = githubHeaders(options.githubToken ?? process.env.GITHUB_TOKEN);
+  const repo = await fetchJson(fetchImpl, `https://api.github.com/repos/${parsed.owner}/${parsed.repo}`, headers);
+  const ref = options.ref ?? repo.default_branch;
+  const tree = await listGitHubRepositoryFiles(fetchImpl, parsed.owner, parsed.repo, ref, headers, options);
+  const communityProfile = await fetchCommunityProfile(fetchImpl, parsed.owner, parsed.repo, headers);
+
+  return createReportFromTree(tree, {
+    root: repo.html_url,
+    source: {
+      type: "github",
+      location: repo.html_url,
+      owner: parsed.owner,
+      repo: parsed.repo,
+      ref,
+      defaultBranch: repo.default_branch,
+      stars: repo.stargazers_count,
+      forks: repo.forks_count,
+      openIssues: repo.open_issues_count,
+      healthPercentage: communityProfile?.health_percentage
+    },
+    communityProfile
+  });
+}
+
+function createReportFromTree(tree, metadata) {
   const fileSet = new Set(tree);
-  const checks = [
+  let checks = [
     ...COMMUNITY_FILES.map((rule) => checkPathRule(rule, fileSet)),
     ...AUTOMATION_FILES.map((rule) => checkMatcherRule(rule, tree)),
     ...PACKAGE_FILES.map((rule) => checkMatcherRule(rule, tree))
   ];
+  checks = applyCommunityProfileEvidence(checks, metadata.communityProfile);
 
   const totalWeight = checks.reduce((sum, check) => sum + check.weight, 0);
   const earnedWeight = checks.filter((check) => check.passed).reduce((sum, check) => sum + check.weight, 0);
@@ -159,8 +211,9 @@ export async function auditRepository(root, options = {}) {
 
   return {
     tool: "oss-signal",
-    version: "0.1.0",
-    root: absoluteRoot,
+    version: VERSION,
+    root: metadata.root,
+    source: metadata.source,
     generatedAt: new Date().toISOString(),
     score,
     grade: gradeForScore(score),
@@ -178,6 +231,7 @@ export function renderMarkdown(report) {
     "# OSS Signal Report",
     "",
     `Repository: \`${report.root}\``,
+    `Source: ${sourceSummary(report.source)}`,
     `Generated: ${report.generatedAt}`,
     "",
     `Score: **${report.score}/100** (${report.grade})`,
@@ -186,13 +240,24 @@ export function renderMarkdown(report) {
     "",
     `- Passed: ${report.summary.passed}`,
     `- Failed: ${report.summary.failed}`,
-    `- Total checks: ${report.summary.total}`,
+    `- Total checks: ${report.summary.total}`
+  ];
+
+  if (report.source?.type === "github") {
+    lines.push(
+      `- Default branch: ${report.source.defaultBranch}`,
+      `- GitHub stars: ${report.source.stars ?? 0}`,
+      `- GitHub community health: ${report.source.healthPercentage ?? "unknown"}`
+    );
+  }
+
+  lines.push(
     "",
     "## Checks",
     "",
     "| Status | Check | Why it matters |",
     "| --- | --- | --- |"
-  ];
+  );
 
   for (const check of report.checks) {
     lines.push(`| ${check.passed ? "PASS" : "FAIL"} | ${escapeTable(check.label)} | ${escapeTable(check.why)} |`);
@@ -253,6 +318,153 @@ export async function listRepositoryFiles(root, options = {}) {
   return files;
 }
 
+export function parseGitHubTarget(target) {
+  if (/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(target)) {
+    const [owner, repo] = target.split("/");
+    return { owner, repo: repo.replace(/\.git$/, "") };
+  }
+
+  let url;
+  try {
+    url = new URL(target);
+  } catch {
+    throw new Error(`Invalid GitHub target: ${target}`);
+  }
+
+  if (url.hostname !== "github.com" && url.hostname !== "www.github.com") {
+    throw new Error(`Only github.com URLs are supported for remote audits: ${target}`);
+  }
+
+  const [owner, repo] = url.pathname.split("/").filter(Boolean);
+  if (!owner || !repo) {
+    throw new Error(`GitHub URL must include owner and repository: ${target}`);
+  }
+  return { owner, repo: repo.replace(/\.git$/, "") };
+}
+
+function isGitHubTarget(target) {
+  return isGitHubUrl(target) || /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(target);
+}
+
+function isGitHubUrl(target) {
+  return /^https?:\/\/(www\.)?github\.com\//.test(target);
+}
+
+async function pathExists(target) {
+  try {
+    await fs.stat(path.resolve(target));
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+
+async function listGitHubRepositoryFiles(fetchImpl, owner, repo, ref, headers, options = {}) {
+  const maxFiles = options.maxFiles ?? 20000;
+  const treeUrl = `https://api.github.com/repos/${owner}/${repo}/git/trees/${encodeURIComponent(ref)}?recursive=1`;
+  const data = await fetchJson(fetchImpl, treeUrl, headers);
+  return (data.tree ?? [])
+    .filter((entry) => entry.type === "blob" && typeof entry.path === "string")
+    .map((entry) => entry.path)
+    .slice(0, maxFiles);
+}
+
+async function fetchCommunityProfile(fetchImpl, owner, repo, headers) {
+  const url = `https://api.github.com/repos/${owner}/${repo}/community/profile`;
+  try {
+    return await fetchJson(fetchImpl, url, headers);
+  } catch (error) {
+    if (error.status === 404) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+async function fetchJson(fetchImpl, url, headers) {
+  if (!fetchImpl) {
+    return requestJson(url, headers);
+  }
+
+  const response = await fetchImpl(url, { headers });
+  if (!response.ok) {
+    const error = new Error(`GitHub API request failed with ${response.status}: ${url}`);
+    error.status = response.status;
+    throw error;
+  }
+  return response.json();
+}
+
+async function requestJson(url, headers) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, { headers }, (response) => {
+      let body = "";
+      response.setEncoding("utf8");
+      response.on("data", (chunk) => {
+        body += chunk;
+      });
+      response.on("end", () => {
+        if ((response.statusCode ?? 500) < 200 || (response.statusCode ?? 500) >= 300) {
+          const error = new Error(`GitHub API request failed with ${response.statusCode}: ${url}`);
+          error.status = response.statusCode;
+          reject(error);
+          return;
+        }
+        try {
+          resolve(JSON.parse(body));
+        } catch (error) {
+          reject(error);
+        }
+      });
+    });
+    request.on("error", reject);
+    request.end();
+  });
+}
+
+function githubHeaders(token) {
+  const headers = {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "oss-signal"
+  };
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+  return headers;
+}
+
+function applyCommunityProfileEvidence(checks, profile) {
+  if (!profile?.files) {
+    return checks;
+  }
+
+  const profileEvidenceByCheck = {
+    readme: profile.files.readme,
+    license: profile.files.license,
+    contributing: profile.files.contributing,
+    security: profile.files.security_policy,
+    "code-of-conduct": profile.files.code_of_conduct_file ?? profile.files.code_of_conduct,
+    "issue-templates": profile.files.issue_template,
+    "pull-request-template": profile.files.pull_request_template
+  };
+
+  return checks.map((check) => {
+    const evidence = profileEvidenceByCheck[check.id];
+    if (check.passed || !evidence) {
+      return check;
+    }
+    const evidenceUrl = evidence.html_url ?? evidence.url ?? "GitHub community profile";
+    return {
+      ...check,
+      passed: true,
+      evidence: [`GitHub community profile: ${evidenceUrl}`]
+    };
+  });
+}
+
 function checkPathRule(rule, fileSet) {
   const matchedPath = rule.paths.find((candidate) => fileSet.has(candidate));
   return {
@@ -324,3 +536,13 @@ function gradeForScore(score) {
 function escapeTable(value) {
   return String(value).replaceAll("|", "\\|");
 }
+
+function sourceSummary(source) {
+  if (!source) {
+    return "local";
+  }
+  if (source.type === "github") {
+    return `GitHub (${source.owner}/${source.repo}@${source.ref})`;
+  }
+  return "local";
+}