actions-warden 0.2.0 → 0.3.0

package/docs/GITHUB-ACTION.md

@@ -0,0 +1,281 @@
+# GitHub Action guide
+
+The bundled JavaScript Action runs the same commands as the CLI on GitHub's
+managed Node 24 runtime. Consumer workflows do not run `npm install`.
+
+## Repository audit
+
+Pin every third-party Action, including actions-warden itself, to a reviewed
+full commit SHA:
+
+```yaml
+name: actions-warden
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # actions-warden-ref: v5.0.0
+        with:
+          persist-credentials: false
+
+      - name: Audit workflows
+        uses: chiz0me/actions-warden@<FULL_COMMIT_SHA>
+        with:
+          command: audit
+          severity: high
+          explain: 'true'
+```
+
+Findings are written to the log, job summary, and native annotations. Audit
+findings fail the step by default.
+
+## Inputs
+
+GitHub passes Action inputs as strings. Boolean values should be quoted in YAML
+for clarity.
+
+| input | default | applies to | behavior |
+|---|---|---|---|
+| `command` | `audit` | all | `audit`, `pin`, `upgrade`, `verify`, `report`, `org-scan`, or `rules` |
+| `workflow` | discovery | repository commands | One path/glob per line or a JSON string array |
+| `severity` | all levels | `audit`, `report`, `org-scan` | Minimum `low`, `medium`, `high`, or `critical` |
+| `format` | `toon` | all | `toon`, `json`, `text`, or `sarif` |
+| `mode` | `minor` | `upgrade`, `report` | `major`, `minor`, or `patch` |
+| `min-age` | `7` | `upgrade`, `report` | Non-negative cooldown in days |
+| `write` | `false` | `pin`, `upgrade` | Apply changes in the checked-out workspace |
+| `fix` | none | `pin`, `upgrade` | Limit work to one exact planned ID |
+| `explain` | `false` | `audit`, `report`, `org-scan` | Include remediation hints |
+| `offline` | `false` | `report` | Skip pin and upgrade network work |
+| `fail-on-findings` | `true` | `audit`, `report`, `org-scan` | Allow findings to be advisory when `false` |
+| `annotations` | `true` | all | Emit native workflow-command annotations |
+| `config` | auto | `audit`, `report`, `org-scan` | Policy path inside the working directory |
+| `ignore-config` | `false` | `audit`, `report`, `org-scan` | Ignore repository policy |
+| `baseline` | policy/default | `audit`, `report`, `org-scan` | Accepted-finding baseline |
+| `organization` | none | `org-scan` | Required organization login |
+| `repository` | all eligible | `org-scan` | One repository glob per line or a JSON string array |
+| `visibility` | `all` | `org-scan` | `all`, `public`, `private`, or `internal` |
+| `include-archived` | `false` | `org-scan` | Include archived repositories |
+| `include-disabled` | `false` | `org-scan` | Include disabled repositories |
+| `include-forks` | `false` | `org-scan` | Include forked repositories |
+| `max-repos` | none | `org-scan` | Positive repository limit |
+| `concurrency` | `4` | `org-scan` | Concurrent repository scans from 1 through 16 |
+| `checkpoint-path` | none | `org-scan` | Create or replace an atomic resumable checkpoint |
+| `resume-from` | none | `org-scan` | Resume from and update an existing checkpoint |
+| `progress` | `true` | `org-scan` | Show discovery, repository, retry, and completion updates in the step log |
+| `output-path` | none | all | Save the selected format inside the working directory |
+| `token` | none | network commands | GitHub API token; normally `${{ github.token }}` or a secret |
+| `working-directory` | `$GITHUB_WORKSPACE` | all | Scan and path-safety root |
+
+`node-version` is a deprecated compatibility input. It is accepted but ignored
+because the Action runtime is declared by the bundle.
+
+Multivalue inputs can be line-separated:
+
+```yaml
+with:
+  workflow: |
+    .github/workflows/release.yml
+    .github/actions
+```
+
+or JSON:
+
+```yaml
+with:
+  repository: '["service-*", "platform-*"]'
+```
+
+## Outputs and failure policy
+
+| output | description |
+|---|---|
+| `status` | Semantic `OK` or `FAIL` |
+| `findings` | Finding count for `audit`, `report`, and `org-scan` |
+| `report-path` | Absolute saved path when `output-path` is supplied |
+| `annotations` | Number of annotations emitted |
+| `annotations-skipped` | Number omitted by the per-level cap |
+
+Give the step an `id` to read outputs:
+
+```yaml
+- name: Audit workflows
+  id: warden
+  uses: chiz0me/actions-warden@<FULL_COMMIT_SHA>
+  with:
+    command: audit
+    fail-on-findings: 'false'
+
+- name: Show result
+  run: echo "status=${{ steps.warden.outputs.status }} findings=${{ steps.warden.outputs.findings }}"
+```
+
+`fail-on-findings: 'false'` changes step failure only for security findings in
+`audit`, `report`, and `org-scan`. It does not hide findings or change the
+`status` output.
+
+Operational failures always fail the step, including:
+
+- invalid or unparseable workflow YAML;
+- organization repository or blob read failures;
+- ref resolution and ownership-verification failures;
+- unsafe paths or writes;
+- errors in the pin or upgrade phases of `report`.
+
+`pin`, `upgrade`, and `verify` errors always fail. Warnings from `verify` do
+not fail.
+
+## Native annotations
+
+Annotations are independent of `format`:
+
+| result | annotation level |
+|---|---|
+| critical or high finding | error |
+| medium finding | warning |
+| low finding | notice |
+| verification warning | warning |
+| resolver, verification, scan, or write error | error |
+
+Local findings attach to the repository-relative file and source line.
+Organization findings belong to other repositories, so they omit a local file
+attachment while retaining repository, remote path, source URL, rule, and
+stable ID in the message and saved report.
+
+The Action emits at most 10 annotations per level per step, with more severe
+records first. All omitted records remain in normal output and saved reports.
+Set `annotations: 'false'` to disable annotations without changing status or
+failure behavior.
+
+Workflow-command data is escaped and credential-like values are redacted before
+emission.
+
+## Save a report artifact
+
+`output-path` writes the selected format in addition to stdout:
+
+```yaml
+- name: Generate report
+  id: warden
+  uses: chiz0me/actions-warden@<FULL_COMMIT_SHA>
+  with:
+    command: report
+    format: json
+    output-path: reports/actions-warden.json
+    fail-on-findings: 'false'
+    token: ${{ github.token }}
+
+- name: Upload report
+  if: always()
+  uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # actions-warden-ref: v5.0.0
+  with:
+    name: actions-warden-report
+    path: ${{ steps.warden.outputs.report-path }}
+    if-no-files-found: error
+```
+
+The output path must remain inside `working-directory`.
+
+## Organization report
+
+The default repository `GITHUB_TOKEN` generally sees only the repository where
+the workflow runs. Use a GitHub App installation token or a fine-grained token
+whose repository access covers the intended organization scope.
+
+```yaml
+name: organization Actions report
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '23 7 * * 1'
+
+permissions:
+  contents: read
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # actions-warden-ref: v5.0.0
+        with:
+          persist-credentials: false
+
+      - name: Scan organization
+        id: warden
+        uses: chiz0me/actions-warden@<FULL_COMMIT_SHA>
+        with:
+          command: org-scan
+          organization: ${{ github.repository_owner }}
+          token: ${{ secrets.ACTIONS_WARDEN_ORG_TOKEN }}
+          severity: high
+          explain: 'true'
+          format: json
+          output-path: actions-warden-org-report.json
+          checkpoint-path: .actions-warden-org-checkpoint.json
+          fail-on-findings: 'false'
+
+      - name: Upload organization report
+        if: always()
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # actions-warden-ref: v5.0.0
+        with:
+          name: actions-warden-org-report
+          path: |
+            actions-warden-org-report.json
+            .actions-warden-org-checkpoint.json
+          if-no-files-found: error
+```
+
+Keep the token in Actions secrets, avoid printing it, and grant only metadata
+and contents read access for selected repositories. The complete copyable file
+is [examples/org-scan.yml](../examples/org-scan.yml).
+
+The Action writes live progress to the step log separately from the selected
+report format. Set `progress: 'false'` to disable it.
+
+CLI `--agent-mode` is not an Action input. The Action already has explicit
+`output-path`, checkpoint, progress, summary, and output channels; configure
+those inputs directly when an agent generates a workflow.
+
+`checkpoint-path` starts a new checkpoint. To resume, restore that file into
+the working directory before the actions-warden step, remove
+`checkpoint-path`, and set `resume-from` to the restored path. The Action does
+not itself retain files between ephemeral runners; use a protected artifact or
+other caller-managed storage. Scope, policy, baseline, package, and rule
+identity must match. Fresh repository discovery and tree checks still occur,
+and changed or previously failed repositories are rescanned. Checkpoints hold
+redacted report evidence about repositories and findings, so protect them like
+the organization report. `checkpoint-path` and `resume-from` are mutually
+exclusive and cannot equal `output-path`.
+
+## Mutation workflows
+
+With `write: 'true'`, `pin` and `upgrade` modify only the runner's checked-out
+working tree. The Action does not commit, push, or open a pull request.
+
+A safe automation flow is:
+
+1. run the command without `write` and retain the report;
+2. require review or select one `fix` ID;
+3. run with `write: 'true'`;
+4. run `verify` and repository tests;
+5. create a pull request using a separately reviewed workflow.
+
+See [examples/upgrade-pr.yml](../examples/upgrade-pr.yml) for an opt-in,
+cooldown-aware upgrade pull request workflow. It uses explicit contents and
+pull-request write permissions only in the mutation job.
+
+## Bundle integrity
+
+The repository commits `dist/index.js` because GitHub Actions executes the
+bundle directly. Releases verify that a clean rebuild matches the committed
+bundle. Consumers should pin the Action to a full commit SHA, then use
+actions-warden's metadata comment to retain the reviewed release name.

package/docs/JAVASCRIPT-API.md

@@ -0,0 +1,355 @@
+# JavaScript API
+
+actions-warden is an ECMAScript module for Node.js 20 or newer. Public command
+functions return structured objects and do not write reports to stdout.
+
+```sh
+npm install actions-warden
+```
+
+```js
+import { audit } from 'actions-warden';
+
+const result = await audit({
+  cwd: '/path/to/repository',
+  severity: 'high',
+  explain: true,
+});
+
+if (result.status === 'FAIL') {
+  for (const finding of result.findings) {
+    console.log(finding.id, finding.ruleId, finding.file, finding.line);
+  }
+}
+```
+
+From CommonJS, use a dynamic import:
+
+```js
+const { audit } = await import('actions-warden');
+```
+
+The raw API result does not include `schemaVersion`; renderers add the versioned
+wire format.
+
+## Command functions
+
+### `audit(options)`
+
+```js
+const result = await audit({
+  cwd,
+  workflows,       // string[] of files, directories, or globs
+  severity,        // low | medium | high | critical
+  explain,         // boolean
+  configPath,      // string, false to disable policy, or undefined for discovery
+  baseline,        // baseline path
+  ignoreBaseline,  // boolean; primarily used while creating a baseline
+});
+```
+
+Returns:
+
+```js
+{
+  files,
+  findings,
+  allFindings,
+  summary,
+  baseline,
+  configPath,
+  status
+}
+```
+
+`findings` reflects severity and baseline filtering. `allFindings` is the
+unfiltered rule output used to create a baseline.
+
+### `auditSources(options)`
+
+Audit caller-supplied YAML without writing it to disk:
+
+```js
+import { auditSources, DEFAULT_CONFIG } from 'actions-warden';
+
+const result = await auditSources({
+  cwd: '/virtual/root',
+  sources: [
+    {
+      file: '/virtual/root/acme/service/.github/workflows/ci.yml',
+      source: workflowYaml,
+    },
+  ],
+  severity: 'high',
+  explain: true,
+  config: DEFAULT_CONFIG,
+});
+```
+
+Every source needs a unique string `file` and string `source`. The function uses
+the same parser, ignore directives, identities, and rules as local audit. It
+does not execute supplied YAML.
+
+When passing a custom config, use the normalized shape returned by `loadConfig`,
+not raw YAML keys.
+
+### `pin(options)`
+
+```js
+const result = await pin({
+  cwd,
+  workflows,
+  dryRun: true,    // default
+  token,
+  fix,             // optional stable change ID
+});
+```
+
+Returns `{ changes, errors, status }`. Set `dryRun: false` only after explicit
+write authorization.
+
+### `verify(options)`
+
+```js
+const result = await verify({ cwd, workflows, token });
+```
+
+Returns `{ files, checks, warnings, errors, status }`. Warnings do not make the
+status fail.
+
+### `upgrade(options)`
+
+```js
+const result = await upgrade({
+  cwd,
+  workflows,
+  dryRun: true,    // default
+  token,
+  mode: 'minor',   // major | minor | patch
+  minAgeDays: 7,
+  fix,
+});
+```
+
+Returns `{ changes, skipped, errors, status }`.
+
+### `report(options)`
+
+```js
+const result = await report({
+  cwd,
+  workflows,
+  token,
+  mode: 'minor',
+  severity: 'high',
+  explain: true,
+  skipResolve: false,
+  minAgeDays: 7,
+  configPath,
+  baseline,
+});
+```
+
+Returns `{ audit, pin, upgrade, offline, status }`. Both mutation phases are
+always dry-runs.
+
+### `scanOrganization(options)`
+
+```js
+const result = await scanOrganization({
+  organization: 'my-org',
+  cwd: process.cwd(),
+  token: process.env.GITHUB_TOKEN,
+  repositories: ['service-*', 'my-org/platform-*'],
+  visibility: 'all',
+  includeArchived: false,
+  includeDisabled: false,
+  includeForks: false,
+  maxRepositories: 100,
+  concurrency: 4,
+  severity: 'high',
+  explain: true,
+  configPath: '.actions-warden.yml',
+  baseline: '.actions-warden-baseline.json',
+  checkpointPath: '.actions-warden-org-checkpoint.json',
+  resume: false,
+  onProgress(event) {
+    console.error(event.type, event.repository ?? '');
+  },
+});
+```
+
+Returns:
+
+```js
+{
+  organization,
+  scope,
+  repositories,
+  findings,
+  errors,
+  summary,
+  baseline,
+  configPath,
+  status
+}
+```
+
+`findings` and `errors` are flattened for ingestion. `repositories` retains
+per-repository identity, revision, files, findings, errors, summary, and status.
+
+The organization scan is read-only and does not clone, check out, execute, or
+persist raw remote workflow sources. Repository failures are accumulated when
+possible; failures that prevent organization discovery throw.
+
+`checkpointPath` explicitly enables atomic checkpoint writes inside `cwd`.
+Set `resume: true` to require, validate, and update an existing checkpoint at
+that path. The organization, selection and audit options, normalized policy,
+baseline contents, package version, and rule catalog must match. Concurrency
+and token changes are allowed. Resume performs fresh discovery and tree reads;
+it reuses only error-free results whose repository, default branch, and tree
+SHA remain unchanged. Checkpoints contain redacted report data and revision
+metadata, never tokens or raw YAML.
+
+`onProgress` may be synchronous or asynchronous and is awaited in event order
+at each emission point. A callback error rejects the scan; repository results
+whose completion event was reached have already been checkpointed. Event
+objects are shallow-frozen and use these `type` values:
+
+| type | important fields |
+|---|---|
+| `scan-started` | `organization` |
+| `checkpoint-loaded` | `repositories` |
+| `checkpoint-created` | none |
+| `discovery-started` | `organization` |
+| `discovery-completed` | `discovered`, `eligible`, `selected` |
+| `repository-started` | `repository`, `position`, `total` |
+| `request-retry` | optional `repository`, `attempt`, `maxRetries`, `reason`, `delayMs`, optional `status` |
+| `repository-completed` | `repository`, `completed`, `total`, `reused`, `status`, `files`, `findings`, `errors` |
+| `scan-completed` | `organization`, `status`, `completed`, `total`, `reused`, `findings`, `errors`, `elapsedMs` |
+
+Progress is observational and is not included in the returned result or its
+rendered wire formats.
+
+The CLI's `--agent-mode` is an output-routing adapter, not a
+`scanOrganization()` option. JavaScript callers already control checkpoint
+paths, progress callbacks, rendering, persistence, and how much of the returned
+object enters an AI context. Implement the same bounded behavior by saving the
+rendered report and returning only `status`, `summary`, and the saved path to
+the agent.
+
+## Renderers
+
+Use the matching renderer to obtain the CLI-compatible wire format:
+
+```js
+import { audit, renderAudit } from 'actions-warden';
+
+const result = await audit({ cwd: '/repo', explain: true });
+
+const json = renderAudit(result, {
+  format: 'json',
+  explain: true,
+  cwd: '/repo',
+});
+
+const toon = renderAudit(result, {
+  format: 'toon',
+  explain: true,
+  cwd: '/repo',
+});
+```
+
+Command/render pairs are:
+
+| command | renderer |
+|---|---|
+| `audit` | `renderAudit` |
+| `pin` | `renderPin` |
+| `upgrade` | `renderUpgrade` |
+| `verify` | `renderVerify` |
+| `report` | `renderReport` |
+| `scanOrganization` | `renderOrganizationScan` |
+
+Lower-level formatters are also exported: `format`, `renderToon`, `renderJson`,
+`renderText`, `renderSarif`, `summarize`, and `SEVERITY_ORDER`.
+
+Every renderer applies credential redaction. See [output contracts](./OUTPUTS.md)
+before depending on the serialized structure.
+
+## Parser and policy utilities
+
+The package root exports:
+
+```js
+import {
+  collectImages,
+  collectUses,
+  discoverWorkflows,
+  isIgnored,
+  loadConfig,
+  parseActionRef,
+  parseIgnoreDirectives,
+  parseWorkflowFile,
+  parseWorkflowSource,
+} from 'actions-warden';
+```
+
+Additional exports include baseline helpers, organization GitHub readers
+(`listOrganizationRepositories`, `fetchRepositoryWorkflowTree`, and
+`fetchRepositoryWorkflows`), redaction, the live rule catalog, and organization
+size limits. A validated workflow-tree snapshot can be supplied to
+`fetchRepositoryWorkflows` to avoid a duplicate tree request. See
+[src/index.js](../src/index.js) for the exact export list in the checked-out
+version.
+
+Command entry points are also available as explicit package subpaths:
+
+```js
+import { audit } from 'actions-warden/commands/audit';
+import { scanOrganization } from 'actions-warden/commands/org-scan';
+```
+
+## Error handling
+
+Command functions use two error channels:
+
+- per-file or per-repository operational problems are usually returned in an
+  `errors` array with status `FAIL`;
+- invalid top-level input, unsafe paths, invalid policy, failed target
+  discovery, or inability to list an organization rejects the promise.
+
+Handle both:
+
+```js
+try {
+  const result = await scanOrganization(options);
+
+  if (result.status === 'FAIL') {
+    for (const error of result.errors) {
+      console.error(error.repository, error.path, error.error);
+    }
+  }
+} catch (error) {
+  console.error('scan could not start:', error.message);
+}
+```
+
+Do not log tokens or raw credentials in an error handler. Built-in renderers
+redact their output; arbitrary caller logging does not.
+
+## Concurrency
+
+Network-backed helpers use bounded concurrency. `pin` and `verify` resolve up to
+four references at once. Organization scans accept `concurrency` from 1 through
+16 and default to 4.
+
+Do not mutate shared workflow files concurrently through multiple `pin` or
+`upgrade` calls. Run a single plan/write cycle for a repository.
+
+## Related guides
+
+- [CLI reference](./CLI.md)
+- [Output contracts](./OUTPUTS.md)
+- [AI and coding agents](./AI-AGENTS.md)
+- [Developer guide](./DEVELOPMENT.md)