@erclx/aitk 2.0.0 → 2.2.0

package/src/audits/catalog.ts

@@ -1,4 +1,6 @@
+import type { AuditRefusal } from '@/deps/audit'
 import type { ValidateRefusal as RecordRefusal } from '@/records/validate'
+import type { ScanRefusal } from '@/secrets/scan'
 import type { ValidateRefusal as BoardRefusal } from '@/tasks/validate'
 
 /**
@@ -16,6 +18,17 @@ export type Corpus =
   | 'tracked'
   /** Gitignored session scratch, so the numbers are one machine's alone. */
   | 'per-machine'
+  /**
+   * Read from an index off this machine, so the count moves when someone
+   * publishes rather than when someone edits here.
+   *
+   * Its own member rather than either of the two above. A baseline would
+   * record growth nobody caused, which is what keeps it out of the retained
+   * set alongside per-machine scratch, and an index this run could not reach
+   * is an ordinary absence rather than the broken checkout a missing tracked
+   * tree would be.
+   */
+  | 'upstream'
 
 export type AuditStatus =
   /** The audit reported and every count it produced is zero. */
@@ -47,6 +60,17 @@ export interface AuditSpec {
    */
   readonly gatingExits: readonly number[]
   readonly corpus: Corpus
+  /**
+   * Refusal reasons that mean this audit has no corpus here rather than that
+   * it broke, overriding what the corpus alone would allow.
+   *
+   * Present only where the corpus answers wrongly. A tracked corpus normally
+   * allows nothing, since a tree that ships to targets and cannot be found is
+   * a broken checkout, and the secret scan is the exception: a project that
+   * publishes nothing has no shipped tree to read, which is an ordinary state
+   * rather than a defect.
+   */
+  readonly absentReasons?: readonly string[]
   /**
    * Pulls the counts worth retaining out of this verb's record.
    *
@@ -62,7 +86,10 @@ export interface AuditResult {
   readonly id: string
   readonly label: string
   readonly status: AuditStatus
+  /** Retained by the baseline, which is `tracked` alone. */
   readonly tracked: boolean
+  /** Why it is or is not retained, which `tracked` alone cannot say. */
+  readonly corpus: Corpus
   readonly exitCode: number
   readonly counts?: Record<string, number>
   /** Why the audit did not report, present only on `unmeasured`. */
@@ -271,6 +298,26 @@ function boardCounts(record: unknown): Record<string, number> | undefined {
   })
 }
 
+/**
+ * Reads the advisory verb's per-severity object rather than a total.
+ *
+ * A single count folds a critical advisory into a low one, and the response to
+ * the two differs. The keys are read off the record rather than listed here,
+ * so a severity the index adds is carried instead of silently dropped.
+ */
+function advisoryCounts(record: unknown): Record<string, number> | undefined {
+  const severities = asObject(asObject(record)?.severities)
+  if (severities === undefined) return undefined
+
+  const counts: Record<string, number> = {}
+  for (const [severity, value] of Object.entries(severities)) {
+    if (typeof value !== 'number') return undefined
+    counts[`advisories-${severity}`] = value
+  }
+
+  return counts
+}
+
 function findingsOnly(record: unknown): Record<string, number> | undefined {
   const root = asObject(record)
   if (root === undefined) return undefined
@@ -318,10 +365,12 @@ const RECORD_KINDS: readonly (readonly [string, Corpus])[] = [
 /**
  * Every audit the aggregate runs.
  *
- * `context`, `markdown`, and `skills` are the three that gate, which is exactly
- * the set `scripts/core/verify.sh` already fails a push on. Adding a fourth
- * here widens what fails a push without anyone deciding to, and the split this
- * repository records gates a fact and reports a judgment.
+ * `context`, `markdown`, and `skills` gate because `scripts/core/verify.sh`
+ * already fails a push on each. `secrets` is the one entry that gates without
+ * a stage behind it, added deliberately rather than as a side effect, since a
+ * credential in the published tree is a fact and the split this repository
+ * records gates a fact and reports a judgment. Weigh any further addition
+ * against that test rather than against the count.
  *
  * Each verb runs once in its fullest form. Running the gating half separately
  * would walk the same tree twice for a number the full record already carries.
@@ -386,6 +435,46 @@ export const AUDITS: readonly AuditSpec[] = [
     corpus: 'tracked',
     counts: testOrderCounts,
   },
+  {
+    id: 'secrets',
+    label: 'Shipped tree secrets',
+    argv: ['secrets', 'scan', '--json'],
+    // The fourth gate, and the first added since the note above was written.
+    // A credential-shaped value sitting in the tree this repository publishes
+    // is a fact rather than a judgment, which is the test that note asks any
+    // addition to pass. It is decided here and stated in the context entry
+    // rather than arriving as a side effect of registering a measure.
+    gatingExits: [EXIT_FINDINGS],
+    corpus: 'tracked',
+    // The three reasons that mean this tree publishes nothing, which is where
+    // most targets installing this CLI sit. Without the allowance the
+    // aggregate reports `incomplete` on every run in every such project and
+    // never changes, which is the permanent signal the per-machine allowance
+    // exists against.
+    //
+    // Two reasons are deliberately left out, and both are a corpus that exists
+    // and went unread. `no-git` is a broken checkout, and `no-files-field` is a
+    // publish that would pack the whole tree, so calling either an absence
+    // would report a pass over a shipped tree nobody measured.
+    absentReasons: [
+      'no-manifest',
+      'no-publish',
+      'no-shipped-files',
+    ] satisfies ScanRefusal[],
+    counts: findingsOnly,
+  },
+  {
+    id: 'deps',
+    label: 'Dependency advisories',
+    argv: ['deps', 'audit', '--json'],
+    // Reports rather than gates, on the same split. A published advisory is a
+    // fact about the index and a judgment about this tree, since the upgrade
+    // may not exist yet, and a push failing on one teaches a contributor to
+    // route around the stage while nothing about the dependency has changed.
+    gatingExits: [],
+    corpus: 'upstream',
+    counts: advisoryCounts,
+  },
 ]
 
 export function auditFor(id: string): AuditSpec | undefined {
@@ -432,6 +521,25 @@ const ABSENT_REASONS: readonly (RecordRefusal | BoardRefusal)[] = [
   'no-board',
 ]
 
+/**
+ * Every reason the advisory verb refuses for, all of which are an absence.
+ *
+ * An index it could not reach, a project that is not JavaScript, and one whose
+ * dependencies were never resolved are three states in which there is nothing
+ * to measure rather than something broken. The verb has no fourth reason, so
+ * this is its whole union rather than a chosen subset, and typing it that way
+ * fails the build if a later reason arrives without this decision being made.
+ *
+ * Typed against that module's own union for the reason the record reasons are:
+ * a literal here would go on matching nothing after a rename and turn every
+ * offline run back into an unmeasured audit.
+ */
+const ADVISORY_ABSENT_REASONS: readonly AuditRefusal[] = [
+  'no-record',
+  'no-lockfile',
+  'no-manifest',
+]
+
 /**
  * Whether a refusal is a folder this machine never created rather than a break.
  *
@@ -443,15 +551,25 @@ const ABSENT_REASONS: readonly (RecordRefusal | BoardRefusal)[] = [
  * A tracked corpus gets no such allowance. That tree ships to targets, so a
  * checkout that cannot find it is broken, and reading the absence as ordinary
  * would report a pass over a corpus nobody measured.
+ *
+ * An upstream corpus takes the allowance for a different reason. Its index is
+ * off this machine, so an offline run reaches nothing through no fault of the
+ * tree, and pinning the verdict at incomplete every time the network is down
+ * is the same signal-nobody-reads failure the per-machine case already names.
  */
+function absentReasonsFor(spec: AuditSpec): readonly string[] {
+  if (spec.absentReasons !== undefined) return spec.absentReasons
+  if (spec.corpus === 'per-machine') return ABSENT_REASONS
+  if (spec.corpus === 'upstream') return ADVISORY_ABSENT_REASONS
+  return []
+}
+
 function isExpectedAbsence(spec: AuditSpec, record: unknown): boolean {
-  if (spec.corpus !== 'per-machine') return false
+  const allowed = absentReasonsFor(spec)
+  if (allowed.length === 0) return false
 
   const reason = asObject(record)?.reason
-  return (
-    typeof reason === 'string' &&
-    (ABSENT_REASONS as readonly string[]).includes(reason)
-  )
+  return typeof reason === 'string' && allowed.includes(reason)
 }
 
 /**
@@ -471,6 +589,7 @@ export function classify(
     id: spec.id,
     label: spec.label,
     tracked: isTracked(spec),
+    corpus: spec.corpus,
     exitCode,
   }
 

package/src/audits/run.ts

@@ -85,6 +85,7 @@ export async function runAudits(
           label: spec.label,
           status: 'unmeasured' as const,
           tracked: spec.corpus === 'tracked',
+          corpus: spec.corpus,
           exitCode: 1,
           reason: `could not be started: ${error instanceof Error ? error.message : String(error)}`,
         }

package/src/cli.ts

@@ -26,6 +26,8 @@ import { register as markdown } from '@/commands/markdown'
 import { register as records } from '@/commands/records'
 import { register as sessions } from '@/commands/sessions'
 import { register as audits } from '@/commands/audits'
+import { register as secrets } from '@/commands/secrets'
+import { register as deps } from '@/commands/deps'
 import { register as upgrade } from '@/commands/upgrade'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 import { palette } from '@/ui'
@@ -63,6 +65,8 @@ function showHelp(): void {
     `${GREY}│${NC}    markdown [cmd]     ${GREY}# Report markdown against the attribute standards (audit)${NC}`,
     `${GREY}│${NC}    records [cmd]      ${GREY}# Session records under .claude/ (validate, size, push, pull)${NC}`,
     `${GREY}│${NC}    sessions [cmd]     ${GREY}# Resolve live sessions to worktree and branch (list)${NC}`,
+    `${GREY}│${NC}    secrets [cmd]      ${GREY}# Read the shipped tree for credential-shaped values (scan)${NC}`,
+    `${GREY}│${NC}    deps [cmd]         ${GREY}# Read the resolved dependency set for advisories (audit)${NC}`,
     `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,
     `${GREY}│${NC}    upgrade            ${GREY}# Reinstall the CLI globally with the manager that installed it${NC}`,
     `${GREY}│${NC}`,
@@ -104,6 +108,8 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk records size --json`,
     `${GREY}│${NC}    aitk records push --json`,
     `${GREY}│${NC}    aitk sessions list --json`,
+    `${GREY}│${NC}    aitk secrets scan --json`,
+    `${GREY}│${NC}    aitk deps audit --json`,
     `${GREY}│${NC}    aitk audits run --json`,
     `${GREY}│${NC}    aitk upgrade --json`,
     `${GREY}└${NC}`,
@@ -148,6 +154,8 @@ context(program)
 markdown(program)
 records(program)
 sessions(program)
+secrets(program)
+deps(program)
 audits(program)
 upgrade(program)
 

package/src/commands/audits.ts

@@ -244,7 +244,11 @@ function countLine(counts: Record<string, number>): string {
  * against an absent baseline says the same as a corpus that did not move.
  */
 function deltaLine(delta: Delta): string | undefined {
-  if (delta.kind === 'per-machine' || delta.kind === 'unmeasured') {
+  if (
+    delta.kind === 'per-machine' ||
+    delta.kind === 'upstream' ||
+    delta.kind === 'unmeasured'
+  ) {
     return undefined
   }
   if (delta.kind === 'unrecorded') return 'No recorded baseline to compare'
@@ -301,7 +305,11 @@ function report(
     }
 
     if (!result.tracked) {
-      logInfo('Per-machine corpus, so no baseline is kept')
+      logInfo(
+        result.corpus === 'upstream'
+          ? 'Upstream index, so no baseline is kept and growth is not this tree'
+          : 'Per-machine corpus, so no baseline is kept',
+      )
       continue
     }
 
@@ -335,7 +343,7 @@ function report(
   // Stated on every run, including a clean one. A count of what passed reads as
   // a verdict on the whole set unless the run also says what it never reached.
   logInfo(
-    `${summary.audited} of ${results.length} corpora measured, ${summary.absent} absent on this machine`,
+    `${summary.audited} of ${results.length} corpora measured, ${summary.absent} absent or unreachable from this machine`,
   )
 
   outro()

package/src/commands/deps.ts

@@ -0,0 +1,173 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import {
+  type Advisory,
+  auditDependencies,
+  type AuditRefusal,
+  countBySeverity,
+  SEVERITIES,
+} from '@/deps/audit'
+import {
+  intro,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+  plural,
+} from '@/ui'
+
+interface AuditCommandOptions {
+  readonly json?: boolean
+}
+
+/** What a reader does about each way the advisory list fails to arrive. */
+const REFUSALS: Record<AuditRefusal, string> = {
+  'no-manifest': 'No package.json here, so there is no dependency set to read.',
+  'no-lockfile':
+    'No lockfile beside the manifest, so no dependency set is resolved yet. Install first.',
+  'no-record':
+    'The advisory lookup returned no record. Check the network, then re-run.',
+}
+
+export function register(program: Command): void {
+  const deps = program
+    .command('deps')
+    .description('Read the installed dependency set for published advisories')
+    .helpOption('-h, --help', 'Show this help message')
+
+  deps
+    .command('audit')
+    .description('Report advisories against the dependencies already resolved')
+    .argument('[path]', 'Project to audit, defaulting to the current directory')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Scope:',
+        "  The resolved dependency set, read through the runtime's own",
+        '  advisory command. This reaches a network, so a lookup that fails',
+        '  refuses rather than reporting a clean tree.',
+        '',
+        'Exit codes:',
+        '  0  no advisory against the resolved set',
+        '  1  refused, with the reason on stderr',
+        '  2  at least one advisory was published',
+        '',
+        'Examples:',
+        '  aitk deps audit',
+        '  aitk deps audit --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (path: string | undefined, opts: AuditCommandOptions) => {
+      process.exitCode = await runAudit(path, opts)
+    })
+}
+
+function severityLine(counts: Record<string, number>): string {
+  return SEVERITIES.filter((severity) => counts[severity] !== 0)
+    .map((severity) => `${counts[severity]} ${severity}`)
+    .join(', ')
+}
+
+/**
+ * Groups by package, since one dependency commonly carries several advisories
+ * and a flat list reads as more distinct upgrades than the tree actually owes.
+ */
+function byPackage(advisories: readonly Advisory[]): Map<string, Advisory[]> {
+  const grouped = new Map<string, Advisory[]>()
+
+  for (const advisory of advisories) {
+    const held = grouped.get(advisory.package) ?? []
+    held.push(advisory)
+    grouped.set(advisory.package, held)
+  }
+
+  return grouped
+}
+
+async function runAudit(
+  path: string | undefined,
+  opts: AuditCommandOptions,
+): Promise<number> {
+  const root = resolve(path ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('aitk deps audit')
+
+  const audit = await auditDependencies(root)
+
+  if (audit.kind === 'refused') {
+    logStep('Refused')
+    logWarn(REFUSALS[audit.reason])
+    if (audit.message !== undefined) logWarn(audit.message)
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          reason: audit.reason,
+          message: audit.message ?? REFUSALS[audit.reason],
+        })}\n`,
+      )
+    }
+    return 1
+  }
+
+  const counts = countBySeverity(audit.advisories)
+
+  logStep('Advisories')
+  if (audit.advisories.length === 0) {
+    logInfo('No advisory against the resolved dependency set.')
+  } else {
+    const grouped = byPackage(audit.advisories)
+    const total = audit.advisories.length
+
+    logWarn(
+      `${total} ${total === 1 ? 'advisory' : 'advisories'} across ${plural(grouped.size, 'package')}: ${severityLine(counts)}`,
+    )
+
+    // Piped rather than logged line by line, since every one of these is a
+    // finding and the timeline's own tick would mark each as something that
+    // passed. The frame stays, and the list inside it stays unmarked.
+    pipeOutput(
+      [...grouped]
+        .map(([name, held]) =>
+          [
+            `${name}: ${severityLine(countBySeverity(held))}`,
+            ...held.flatMap((advisory) => [
+              `  ${advisory.severity.padEnd(8)} ${advisory.title}`,
+              `  ${' '.repeat(8)} ${advisory.url}`,
+            ]),
+          ].join('\n'),
+        )
+        .join('\n'),
+    )
+  }
+
+  // Stated whichever way the count went. An advisory arrives when someone
+  // publishes one, so this number moves with no edit here, and a report that
+  // does not date itself reads as a fact about the tree rather than about a day.
+  logStep('Reading')
+  logInfo(
+    'Measured against the advisory index at run time, not at commit time.',
+  )
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        severities: counts,
+        advisories: audit.advisories,
+      })}\n`,
+    )
+  }
+
+  return audit.advisories.length === 0 ? 0 : 2
+}

package/src/commands/secrets.ts

@@ -0,0 +1,132 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { type ScanRefusal, scanShippedTree } from '@/secrets/scan'
+import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
+
+interface ScanCommandOptions {
+  readonly json?: boolean
+}
+
+/** What a reader does about each way the corpus fails to build. */
+const REFUSALS: Record<ScanRefusal, string> = {
+  'no-manifest':
+    'No package.json here, so nothing is published from this tree.',
+  'no-publish':
+    'The manifest declares private, so this project publishes nothing.',
+  // Stated as an unread corpus rather than an absent one. A publish with no
+  // files field packs the whole tree, so this is the package that ships the
+  // most, and calling it nothing to read is the denial the reasoning in
+  // src/secrets/shipped.ts warns against.
+  'no-files-field':
+    'package.json declares no files field, so a publish would pack the whole tree. This check reads a declared corpus and left that one unread.',
+  'no-git': 'git could not list this tree, so the corpus is unknown.',
+  'no-shipped-files':
+    'The files field matched nothing git lists, so nothing would be scanned.',
+}
+
+export function register(program: Command): void {
+  const secrets = program
+    .command('secrets')
+    .description('Read committed state for credentials that ship to a target')
+    .helpOption('-h, --help', 'Show this help message')
+
+  secrets
+    .command('scan')
+    .description('Report credential-shaped values in the tree this repo ships')
+    .argument(
+      '[path]',
+      'Repository to scan, defaulting to the current directory',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Scope:',
+        "  The package's own files field, so the corpus is what npm packs",
+        '  and what the plugin ships. Nothing outside it is read.',
+        '',
+        'Exit codes:',
+        '  0  the shipped tree carries no credential-shaped value',
+        '  1  refused, with the reason on stderr',
+        '  2  at least one value was found',
+        '',
+        'Examples:',
+        '  aitk secrets scan',
+        '  aitk secrets scan --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (path: string | undefined, opts: ScanCommandOptions) => {
+      process.exitCode = await runScan(path, opts)
+    })
+}
+
+async function runScan(
+  path: string | undefined,
+  opts: ScanCommandOptions,
+): Promise<number> {
+  const root = resolve(path ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('aitk secrets scan')
+
+  const scan = await scanShippedTree(root)
+
+  if (scan.kind === 'refused') {
+    logStep('Refused')
+    logWarn(REFUSALS[scan.reason])
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          reason: scan.reason,
+          message: REFUSALS[scan.reason],
+        })}\n`,
+      )
+    }
+    return 1
+  }
+
+  logStep('Corpus')
+  logInfo(
+    `${plural(scan.files, 'file')} read, ${scan.skipped} skipped as binary or unreadable`,
+  )
+  // Stated on every run, including a clean one. The corpus answers what the
+  // package publishes, and a reader who sees only the passing count reads the
+  // verdict as covering the repository.
+  logInfo(
+    `${scan.listed - scan.files - scan.skipped} of ${scan.listed} listed files sit outside the published corpus and were not read`,
+  )
+
+  logStep('Findings')
+  if (scan.findings.length === 0) {
+    logInfo('No credential-shaped value in the shipped tree.')
+  } else {
+    logError(plural(scan.findings.length, 'value'))
+    for (const finding of scan.findings) {
+      logWarn(
+        `${finding.file}:${finding.line}:${finding.column}  ${finding.label}  ${finding.preview}`,
+      )
+    }
+  }
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        files: scan.files,
+        skipped: scan.skipped,
+        listed: scan.listed,
+        findings: scan.findings,
+      })}\n`,
+    )
+  }
+
+  return scan.findings.length === 0 ? 0 : 2
+}