@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.4

package/packages/repo-controls/src/doctor.ts

@@ -0,0 +1,304 @@
+import { createHash } from 'node:crypto'
+import { existsSync, lstatSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import {
+  azureDevOpsGovernanceChecks,
+  type AzureDevOpsPolicyReader,
+} from './azure-devops-governance.ts'
+import { loadComplianceConfig } from './compliance-config.ts'
+import { loadConfig } from './config.ts'
+import {
+  ADL_NPM_INSTALL,
+  COMPLIANCE_ROOT,
+  HOOK_NAMES,
+  HOOKS_PATH,
+  INSTALL_HINT,
+  LOCK_REL,
+  MANAGED_ASSETS,
+  TOOL,
+  VERSION,
+} from './constants.ts'
+import { checkGitignoreBlock } from './gitignore-block.ts'
+import { type Lock, readLock, stubText } from './install.ts'
+import { bashProblem, capture, type Env, gitConfigGet, resolveRepo, which } from './runtime.ts'
+
+export interface Check {
+  id: string
+  status: 'ok' | 'warn' | 'fail'
+  message: string
+}
+
+export interface DoctorReport {
+  repo: string
+  ok: boolean
+  checks: Check[]
+}
+
+export interface DoctorOptions {
+  complianceRoot?: string
+  readAzureDevOpsPolicyEvidence?: AzureDevOpsPolicyReader
+  /**
+   * Whether to include the network + minted-token Azure DevOps
+   * promotion-governance checks (`azure-devops.remote`,
+   * `azure-devops.policy-read`, `azure-devops.minimum-review`,
+   * `azure-devops.build-policy`). Defaults to `true`: a bare
+   * `adl-repo-controls doctor` run keeps reporting everything.
+   *
+   * Set to `false` for the pre-commit gate only (Tarun, 2026-09-28): those
+   * checks need network access and a minted Azure DevOps token, which a
+   * `git commit` must never require — they moved to the pre-push gate
+   * instead (see `azureDevOpsPromotionGovernanceChecks` /
+   * `azureDevOpsPromotionGovernanceGate` in `./hook.ts`, and README's hooks
+   * section).
+   */
+  includeAzureDevOpsGovernance?: boolean
+}
+
+const errorText = (error: unknown): string => (error as Error).message
+
+/**
+ * The declared Azure DevOps promotion-governance checks alone: the
+ * configured remote parsed, then the target branch's remote policies read
+ * over the network with a minted token. Returns `[]` when the repository
+ * declares no `[controls.release]` at all — there is nothing to prove.
+ *
+ * Split out of `doctor()` (Tarun, 2026-09-28) so the pre-push gate can run
+ * exactly these checks on their own, without re-running (or skipping) every
+ * other doctor check — see `azureDevOpsPromotionGovernanceGate` in `./hook.ts`.
+ */
+export function azureDevOpsPromotionGovernanceChecks(
+  repo: string,
+  env: Env,
+  readAzureDevOpsPolicyEvidence?: AzureDevOpsPolicyReader,
+): Check[] {
+  const config = loadConfig(repo)
+  if (!config.release.source && !config.release.target) return []
+  const remote = capture(['git', 'remote', 'get-url', config.prePush.remote], repo, env)
+  if (remote.code !== 0) {
+    return [
+      {
+        id: 'azure-devops.remote',
+        status: 'fail',
+        message: `could not read configured remote ${config.prePush.remote}: ${remote.stderr.trim() || 'no diagnostic'}`,
+      },
+    ]
+  }
+  return azureDevOpsGovernanceChecks({
+    repo,
+    remote: remote.stdout.trim(),
+    target: config.release.target,
+    env,
+    readEvidence: readAzureDevOpsPolicyEvidence,
+  })
+}
+
+/** Read-only health report; exit status is driven by `fail` checks only. */
+export function doctor(repoArg: string, env: Env, options: string | DoctorOptions = COMPLIANCE_ROOT): DoctorReport {
+  const { complianceRoot, readAzureDevOpsPolicyEvidence, includeAzureDevOpsGovernance } =
+    typeof options === 'string'
+      ? { complianceRoot: options, readAzureDevOpsPolicyEvidence: undefined, includeAzureDevOpsGovernance: true }
+      : {
+          complianceRoot: options.complianceRoot ?? COMPLIANCE_ROOT,
+          readAzureDevOpsPolicyEvidence: options.readAzureDevOpsPolicyEvidence,
+          includeAzureDevOpsGovernance: options.includeAzureDevOpsGovernance ?? true,
+        }
+  const checks: Check[] = []
+  const add = (id: string, problem: string | null, okMessage: string, status: Check['status'] = 'fail'): void => {
+    checks.push(problem === null ? { id, status: 'ok', message: okMessage } : { id, status, message: problem })
+  }
+  const finish = (repo: string): DoctorReport => ({ repo, ok: checks.every((check) => check.status !== 'fail'), checks })
+
+  add('bash', bashProblem(env), 'bash >= 4 on PATH')
+  const bun = which('bun', env)
+  add('bun', bun ? null : 'bun not found on PATH (the bundled enact-m5 scripts run with bun)', `bun at ${bun}`)
+  // Checks for `adl`, not TOOL ("adl-repo-controls"): the installed git-hook
+  // stubs exec `adl repo controls hook <name>` (adl-m3-finish item 1,
+  // 2026-09-27 — see install.ts's `stubText`), never a standalone
+  // `adl-repo-controls` binary, which is not published and never on PATH by
+  // design. TOOL stays this package's own internal identity (USAGE text,
+  // the lock file's `tool` field) — a different thing from what a repo's
+  // hooks actually require at runtime.
+  const binary = which('adl', env)
+  add('binary', binary ? null : `adl not found on PATH (hook stubs exec it) — ${ADL_NPM_INSTALL}`, `adl at ${binary}`)
+  // Compliance package (Python, uv-managed) was removed in the monorepo
+  // restructure; install logic is being rebuilt without it. Skip the check
+  // entirely until the new install ships its own surface declaration.
+  void complianceRoot
+
+  let repo: string
+  try {
+    repo = resolveRepo(repoArg)
+  } catch (error) {
+    add('repo', errorText(error), '')
+    return finish(resolve(repoArg))
+  }
+  add('repo', null, repo)
+
+  try {
+    const config = loadConfig(repo)
+    add('config', null, 'adl-config.toml [controls] is valid')
+    // gate-integrity finding, 2026-09-17: "[controls.integrity].watched is
+    // declared in one repository" — an empty list means only the fixed
+    // wiring (adl-config.toml) and any top-level compliance/workflows roots
+    // are protected; this repository's own tsconfig, lint config, coverage
+    // baselines and CI pipeline definitions can then be edited in a normal
+    // commit with no review gate. Advisory (warn): a repository with
+    // genuinely no such files of its own is not a doctor failure.
+    add(
+      'integrity-watched',
+      config.integrity.watched.length === 0
+        ? '[controls.integrity].watched is empty — this repository\'s own gate-defining files (tsconfig, lint config, coverage baselines, CI pipeline) are not protected by the pre-commit integrity gate; declare them under [controls.integrity].watched'
+        : null,
+      `[controls.integrity].watched declares ${config.integrity.watched.length} pattern(s)`,
+      'warn',
+    )
+    // The path the pre-push ratchet grades, not a default: a repository that
+    // declares `[controls.coverage].summary` elsewhere was probed at the wrong
+    // file and passed with its real summary missing.
+    const coverageSummaryExists = existsSync(join(repo, config.coverage.summary))
+    add(
+      'coverage-summary',
+      config.prePush.coverageRatchet && !coverageSummaryExists
+        ? `pre_push.coverage_ratchet is enabled but ${config.coverage.summary} does not exist — the first push will be rejected until it does; commit a baseline or set pre_push.coverage_ratchet = false`
+        : null,
+      `${config.coverage.summary} is present or the ratchet is disabled`,
+    )
+    // Opt-in, like coverage_ratchet: silent when findings_ratchet is unset, so
+    // a repo with no lint tooling at all (enact-repo-controls-m5,
+    // enact-extensions, enact-vps-m5) is never asked for a floor it has no
+    // use for.
+    const findingsFloorExists = existsSync(join(repo, config.findings.floor))
+    add(
+      'findings-floor',
+      config.prePush.findingsRatchet && !findingsFloorExists
+        ? `pre_push.findings_ratchet is enabled but ${config.findings.floor} does not exist — the first push will be rejected until it does; commit a floor or set pre_push.findings_ratchet = false`
+        : null,
+      `${config.findings.floor} is present or the ratchet is disabled`,
+    )
+    // A floor on its own measures nothing. The gate refuses to run with an
+    // empty counter list rather than passing every push, so say it here
+    // instead of letting someone find out when a push is rejected.
+    add(
+      'findings-counters',
+      config.prePush.findingsRatchet && Object.keys(config.findings.counters).length === 0
+        ? 'pre_push.findings_ratchet is enabled but [controls.findings.counters] declares none — a ratchet with nothing to measure grades nothing, so the push is rejected; declare at least one counter or set pre_push.findings_ratchet = false'
+        : null,
+      'at least one findings counter is declared, or the ratchet is disabled',
+    )
+    // A release declaration is a claim that this repository promotes through a
+    // PR. That claim is only armed when the remote branch policies are proved
+    // here. Repositories with no release declaration remain outside this
+    // promotion-specific contract. Skipped entirely when the caller opts out
+    // (the pre-commit gate, since these checks need network + a minted
+    // token) — a bare `doctor` run keeps proving them by default.
+    if (includeAzureDevOpsGovernance) {
+      checks.push(...azureDevOpsPromotionGovernanceChecks(repo, env, readAzureDevOpsPolicyEvidence))
+    }
+  } catch (error) {
+    add('config', errorText(error), '')
+  }
+
+  let complianceEnabled = false
+  try {
+    const complianceConfig = loadComplianceConfig(repo)
+    add('compliance-config', null, 'adl-config.toml [compliance] is valid')
+    complianceEnabled = complianceConfig.enabled.length > 0
+    // gate-integrity finding, 2026-09-17: "docs.ledger is armed in one
+    // repository only" — a repository with a plans/ tree implies the ledger
+    // contract (DOC-009); report it here rather than let it stay
+    // unenforced and undetected. A gate is armed by its exact address
+    // (docs.ledger), its gate id (DOC-009), or its whole domain (docs) —
+    // same three forms [controls.compliance].enabled itself documents.
+    const hasPlans = existsSync(join(repo, 'plans')) && lstatSync(join(repo, 'plans')).isDirectory()
+    const ledgerArmed = ['docs.ledger', 'DOC-009', 'docs'].some((address) => complianceConfig.enabled.includes(address))
+    add(
+      'docs-ledger-armed',
+      hasPlans && !ledgerArmed
+        ? 'this repository has a plans/ tree but docs.ledger is not in [controls.compliance].enabled — the knowledge-ledger contract (DOC-009) is unenforced'
+        : null,
+      hasPlans ? 'docs.ledger is armed for this plans/ tree' : 'no plans/ tree, so docs.ledger is not required',
+      'warn',
+    )
+  } catch (error) {
+    add('compliance-config', errorText(error), '')
+  }
+  const uv = which('uv', env)
+  add(
+    'uv',
+    complianceEnabled && !uv ? 'uv not found on PATH — required by `run compliance` because [compliance].enabled is non-empty (see README)' : null,
+    'uv on PATH, or [compliance].enabled is empty so it is not required',
+  )
+  const astGrep = which('ast-grep', env)
+  add(
+    'ast-grep',
+    complianceEnabled && !astGrep
+      ? 'ast-grep not found on PATH — every compliance row that needs it reports could-not-run, never a pass; 26 rows are affected (see README)'
+      : null,
+    'ast-grep on PATH, or [compliance].enabled is empty so it is not required',
+    'warn',
+  )
+
+  let lock: Lock | null = null
+  try {
+    lock = readLock(repo)
+    add('lock', lock ? null : `${LOCK_REL} missing — ${INSTALL_HINT}`, `${LOCK_REL} is readable`)
+  } catch (error) {
+    add('lock', errorText(error), '')
+  }
+
+  for (const asset of MANAGED_ASSETS) {
+    const path = join(repo, asset.rel)
+    const canonical = readFileSync(asset.source)
+    const canonicalHash = createHash('sha256').update(canonical).digest('hex')
+    const problem = ((): string | null => {
+      const stats = lstatSync(path, { throwIfNoEntry: false })
+      if (stats === undefined) return `${asset.rel} is missing — ${INSTALL_HINT}`
+      if (stats.isSymbolicLink() || !stats.isFile()) return `${asset.rel} is not a real file — ${INSTALL_HINT}`
+      if (!readFileSync(path).equals(canonical)) return `${asset.rel} differs from the installed asset — ${INSTALL_HINT}`
+      if (lock?.files[asset.rel]?.sha256 !== canonicalHash) {
+        return `${asset.rel} lock hash does not match the installed asset — ${INSTALL_HINT}`
+      }
+      if ((stats.mode & 0o111) === 0) return `${asset.rel} is not executable — ${INSTALL_HINT}`
+      return null
+    })()
+    add(asset.doctorId, problem, `${asset.rel} matches the installed asset and lock`)
+  }
+
+  for (const name of HOOK_NAMES) {
+    const rel = `${HOOKS_PATH}/${name}`
+    const path = join(repo, rel)
+    let problem: string | null = null
+    if (!existsSync(path)) problem = `${rel} is missing — ${INSTALL_HINT}`
+    else if (readFileSync(path, 'utf8') !== stubText(name)) problem = `${rel} differs from the installed stub — ${INSTALL_HINT}`
+    else if ((lstatSync(path).mode & 0o111) === 0) problem = `${rel} is not executable — ${INSTALL_HINT}`
+    add(`hook:${name}`, problem, `${rel} is the managed stub`)
+  }
+
+  const hooksPath = gitConfigGet(repo, 'core.hooksPath')
+  const hooksPathProblem = ((): string | null => {
+    if (hooksPath !== HOOKS_PATH) {
+      return `core.hooksPath is ${hooksPath === null ? 'unset' : JSON.stringify(hooksPath)}, expected ${HOOKS_PATH} — ${INSTALL_HINT}`
+    }
+    // The configured value matches, but git does not verify the directory it
+    // names actually exists — a missing/renamed hooksPath silently runs no
+    // hooks at all instead of erroring, so this check must confirm the
+    // directory is real rather than trust the string alone.
+    const hooksDir = join(repo, hooksPath)
+    if (!existsSync(hooksDir) || !lstatSync(hooksDir).isDirectory()) {
+      return `core.hooksPath is ${JSON.stringify(hooksPath)} but that directory does not exist — git silently runs no hooks when core.hooksPath is dangling — ${INSTALL_HINT}`
+    }
+    return null
+  })()
+  add('core.hooksPath', hooksPathProblem, `core.hooksPath = ${HOOKS_PATH}`)
+
+  const gitignoreReport = checkGitignoreBlock(repo)
+  add(
+    'gitignore',
+    gitignoreReport.ok ? null : gitignoreReport.findings.map((finding) => finding.message).join('; '),
+    'the adl managed .gitignore block is present and current',
+  )
+
+  const lockVersion = lock?.version ?? 'nothing (no lock)'
+  add('version', lockVersion === VERSION ? null : `lock written by ${lockVersion}, running ${VERSION}`, `lock written by ${VERSION}`, 'warn')
+  return finish(repo)
+}

package/packages/repo-controls/src/findings-ratchet.ts

@@ -0,0 +1,163 @@
+/**
+ * The static-analysis findings ratchet: a DECLARATION OF FILES, not a count.
+ *
+ * `[controls.findings]` has been parsed, defaulted, exported into every
+ * bundled-script child process, documented in the README and warned about by
+ * `doctor` since before this file existed — and nothing read any of it. The
+ * floor was config with no gate behind it. This is the gate.
+ *
+ * WHY PATHS AND NOT A NUMBER
+ *   A count floor passes the moment one finding is fixed and another appears
+ *   somewhere new, which is the exact regression a ratchet exists to stop. The
+ *   Python side made the same mistake with `granted()` and it was corrected the
+ *   same way: "today's paths will be granted.. not any new", "not number...
+ *   exact file". A listed file is amnestied entirely, however many findings it
+ *   holds; a file NOT listed must be clean. New code is therefore held to the
+ *   full ruleset with no cleanup project first.
+ *
+ * WHAT IT GRADES, per section:
+ *   found - declared  -> REGRESSION. Fails, naming each undeclared file.
+ *   declared - found  -> that file is now clean. Reported as "delete this
+ *                        line". Does NOT fail: failing would punish someone
+ *                        for fixing code, and this gate never edits the floor.
+ *
+ * WHY A COUNTER'S EXIT CODE STILL MATTERS
+ *   The floor file's own header says the tools' exit codes are ignored, and
+ *   `config.ts` says a non-zero counter is a failure. Both are right, about
+ *   different processes. The COUNTER is a repository-authored command that
+ *   wraps the tool; it is expected to swallow "the tool found issues" and still
+ *   exit 0 having printed the paths. A non-zero COUNTER means the counter
+ *   itself did not run — a broken pipe, a missing binary — and that is
+ *   could-not-run, never "zero findings" and never a pass. An empty stdout from
+ *   a counter that exited 0 is a real, and very good, result.
+ *
+ * NO TOOL NAME APPEARS IN THIS FILE. The repository declares its counters and
+ * what each one runs; the package knows a name and a command, the same division
+ * `pre_push.static_checks` already draws.
+ */
+
+/** `counter -> section -> declared files`. */
+export type Floor = Record<string, Record<string, string[]>>
+
+export interface FindingProblem {
+  /** Whether this blocks the push. A file that became clean does not. */
+  fails: boolean
+  message: string
+}
+
+const SCHEMA = 'adl.findings-ratchet/v2'
+
+/**
+ * Parses the floor.
+ *
+ * Deliberately a small hand-rolled reader rather than a YAML dependency: the
+ * floor is a two-level map of string lists and nothing else, and this package
+ * ships no YAML parser to the TypeScript side. A shape it does not understand
+ * is an error, never a silently empty floor — an empty floor would amnesty
+ * nothing and fail every file, which reads as catastrophe rather than as the
+ * misconfiguration it is.
+ */
+export function parseFloor(text: string): Floor {
+  const floor: Floor = {}
+  let counter = ''
+  let section = ''
+  let sawSchema = false
+
+  for (const raw of text.split('\n')) {
+    const line = raw.replace(/\s+$/, '')
+    if (line === '' || line.trimStart().startsWith('#')) continue
+
+    const schema = /^schema:\s*(\S+)$/.exec(line)
+    if (schema) {
+      sawSchema = true
+      if (schema[1] !== SCHEMA) {
+        throw new Error(`findings floor must declare schema: ${SCHEMA} (found ${schema[1]})`)
+      }
+      continue
+    }
+    const item = /^\s{4,}-\s+(\S.*)$/.exec(line)
+    if (item) {
+      if (counter === '' || section === '') throw new Error(`findings floor: stray list item ${line.trim()}`)
+      floor[counter]?.[section]?.push(item[1] as string)
+      continue
+    }
+    const sectionKey = /^\s{2}([A-Za-z0-9_.-]+):\s*$/.exec(line)
+    if (sectionKey) {
+      if (counter === '') throw new Error(`findings floor: section ${sectionKey[1]} outside any counter`)
+      section = sectionKey[1] as string
+      ;(floor[counter] as Record<string, string[]>)[section] = []
+      continue
+    }
+    const counterKey = /^([A-Za-z0-9_.-]+):\s*$/.exec(line)
+    if (counterKey) {
+      counter = counterKey[1] as string
+      section = ''
+      floor[counter] = {}
+      continue
+    }
+    throw new Error(`findings floor: cannot read line: ${line.trim()}`)
+  }
+  if (!sawSchema) throw new Error(`findings floor must declare schema: ${SCHEMA}`)
+  return floor
+}
+
+/**
+ * A counter's stdout into `section -> files`.
+ *
+ * One finding location per line. `category<TAB>path` files the path under that
+ * category, because the floor is sectioned by one and a flat path set would let
+ * a file move between sections unnoticed. A bare `path` is filed under the
+ * counter's own name, so a single-category tool needs no tab and no ceremony.
+ */
+export function parseCounterOutput(counter: string, stdout: string): Map<string, Set<string>> {
+  const sections = new Map<string, Set<string>>()
+  for (const raw of stdout.split('\n')) {
+    const line = raw.trim()
+    if (line === '') continue
+    const tab = raw.indexOf('\t')
+    const section = tab === -1 ? counter : raw.slice(0, tab).trim()
+    const path = tab === -1 ? line : raw.slice(tab + 1).trim()
+    if (path === '') continue
+    const bucket = sections.get(section) ?? new Set<string>()
+    bucket.add(path)
+    sections.set(section, bucket)
+  }
+  return sections
+}
+
+/** Set difference both ways, per section. */
+export function findingsProblems(
+  counter: string,
+  found: Map<string, Set<string>>,
+  floor: Floor,
+): FindingProblem[] {
+  const declaredBySection = floor[counter] ?? {}
+  const problems: FindingProblem[] = []
+
+  for (const [section, paths] of found) {
+    const declared = new Set(declaredBySection[section] ?? [])
+    const regressions = [...paths].filter((path) => !declared.has(path)).sort()
+    if (regressions.length > 0) {
+      problems.push({
+        fails: true,
+        message:
+          `${counter}/${section}: ${regressions.length} file(s) carry findings and are not declared ` +
+          `in the floor:\n${regressions.map((p) => `      - ${p}`).join('\n')}`,
+      })
+    }
+  }
+
+  for (const [section, declared] of Object.entries(declaredBySection)) {
+    const paths = found.get(section) ?? new Set<string>()
+    const cleaned = declared.filter((path) => !paths.has(path)).sort()
+    if (cleaned.length > 0) {
+      problems.push({
+        fails: false,
+        message:
+          `${counter}/${section}: ${cleaned.length} declared file(s) are now clean — delete these ` +
+          `lines from the floor:\n${cleaned.map((p) => `      - ${p}`).join('\n')}`,
+      })
+    }
+  }
+  return problems
+}