@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.12 → 0.1.28

package/packages/repo-controls/src/compliance-config.ts

@@ -17,6 +17,115 @@ export interface ComplianceConfig {
    * outright until this key existed.
    */
   declarations: Record<string, string>
+  /**
+   * Root-level names this repository adds to the engine's standard root allow-list,
+   * from `[controls.compliance.root]`. OMITTED (not `undefined`-valued, not empty)
+   * when the repository declares no `root` table, so a repository that declares
+   * nothing parses to exactly the shape it always did. `hook.ts` turns each
+   * non-empty list into one `--declare root-files=a,b` / `root-dirs=x,y` flag.
+   */
+  root?: RootDeclaration
+  /**
+   * Engine limits this repository sets for itself, from `[controls.compliance.limits]`.
+   * OMITTED (not `undefined`-valued) when the repository declares no `limits` table,
+   * for the same whole-object-shape reason as `root`. A key absent inside the table
+   * keeps the engine's own default. `hook.ts` turns a set `scripts_direct_files`,
+   * `open_gaps` and `open_plans` into `--declare scripts-direct-files=<n>`,
+   * `--declare open-gaps=<n>` and `--declare open-plans=<n>`.
+   */
+  limits?: LimitsDeclaration
+  /**
+   * Extra Markdown roots this repository declares, from `[controls.compliance.markdown]`.
+   * OMITTED (not `undefined`-valued) when the repository declares no `markdown` table,
+   * for the same whole-object-shape reason as `root` and `limits`. `hook.ts` turns a
+   * non-empty `roots` into one `--declare markdown-roots=a,b` flag.
+   */
+  markdown?: MarkdownDeclaration
+  /**
+   * The manifest and lockfile paths REP-002 scans and grades, from
+   * `[controls.compliance.lockfiles]`. OMITTED (not `undefined`-valued) when the
+   * repository declares no `lockfiles` table, for the same whole-object-shape reason
+   * as `root`, `limits` and `markdown`. `hook.ts` turns each non-empty list into one
+   * `--declare bun-manifests=a,b` (and `bun-lockfiles`, `cargo-manifests`,
+   * `cargo-lockfiles`) flag.
+   */
+  lockfiles?: LockfilesDeclaration
+  /**
+   * LAY-004's per-tree direct-file ceilings, from `[controls.compliance.directory-ratchet]`.
+   * OMITTED (not `undefined`-valued) when the repository declares no
+   * `directory-ratchet` table, for the same whole-object-shape reason as `root`,
+   * `limits`, `markdown` and `lockfiles`. `hook.ts` turns a non-empty `max_children`
+   * into one `--declare directory-ceilings=<path>:<n>,<path>:<n>` flag, entries sorted
+   * for deterministic argv.
+   */
+  directory_ratchet?: DirectoryRatchetDeclaration
+}
+
+/**
+ * `[controls.compliance.directory-ratchet]`: LAY-004's RULE — the per-tree
+ * direct-file ceilings, configuration the generic ratchet principle
+ * (2026-10-02) moved out of the register, which records state (exemption
+ * baselines) only. A ceiling is `max_children.<path> = <n>`: every directory
+ * at or below `<path>` (measured per directory) may hold at most `<n>` direct
+ * files unless the register records an exemption. Defaults to empty (nothing
+ * configured: the gate is inert, the same "no configuration = nothing to
+ * enforce" reading DOC-012's cap has).
+ */
+interface DirectoryRatchetDeclaration {
+  /** Repo-relative tree path -> its direct-file ceiling (a positive integer). */
+  max_children: Record<string, number>
+}
+
+/**
+ * `[controls.compliance.lockfiles]`: exactly which paths REP-002 scans and grades. An
+ * ecosystem (Bun, Cargo) is declared as a PAIR, a manifests list and a lockfiles list,
+ * and a declared pair REPLACES that ecosystem's tree-derived default, in what selects the
+ * gate and in what it grades. All four default to empty (nothing declared: the default).
+ */
+interface LockfilesDeclaration {
+  /** `package.json` paths or globs, e.g. `package.json`, `apps/*\/package.json`. */
+  bun_manifests: string[]
+  /** Literal `bun.lock` paths; each must exist and be non-empty. */
+  bun_lockfiles: string[]
+  /** `Cargo.toml` paths or globs. */
+  cargo_manifests: string[]
+  /** Literal `Cargo.lock` paths; each one's directory is the cargo workspace graded. */
+  cargo_lockfiles: string[]
+}
+
+/** The four keys, in the order `hook.ts` sends them: the Bun pair, then the Cargo pair. */
+export const LOCKFILE_KEYS = ['bun_manifests', 'bun_lockfiles', 'cargo_manifests', 'cargo_lockfiles'] as const
+
+/**
+ * `[controls.compliance.markdown]`: directories whose Markdown is site or application
+ * content rather than documentation (an Astro site's `src/content/**\/*.md`). LAY-006
+ * admits Markdown beneath each in addition to the docs trees, so a declared root only
+ * ever widens its allowlist. Defaults to empty.
+ */
+interface MarkdownDeclaration {
+  /** Repository-relative directories, trailing `/` normalised away. */
+  roots: string[]
+}
+
+/** `[controls.compliance.root]`: names directly under the repository root. Both lists default to empty. */
+interface RootDeclaration {
+  files: string[]
+  dirs: string[]
+}
+
+/**
+ * `[controls.compliance.limits]`: engine limits a repository overrides. Every key
+ * is optional and, absent, leaves the engine default in force.
+ */
+interface LimitsDeclaration {
+  /** LAY-014's direct-file limit per scripts directory. The engine default is 15. */
+  scripts_direct_files?: number
+  /** LAY-016's cap on open gaps in the gap register. The engine default is 10. */
+  open_gaps?: number
+  /** LAY-016's cap on open plans (Features). Independent of `open_gaps`. The engine default is 10. */
+  open_plans?: number
+  /** DOC-012's page cap per docs/ directory. The engine default is 15. */
+  docs_pages_per_directory?: number
 }
 
 /**
@@ -36,7 +145,7 @@ const ENABLED_SEED_COMMENT = `# Nothing is graded until a gate is named here. A
 # the packaged defaults are shaped after the repo these checks were authored
 # against, so an enabled row with unpointed trees grades the wrong files.`
 
-export const SEEDED_COMPLIANCE_ATTRIBUTES: SeededAttribute[] = [
+const SEEDED_COMPLIANCE_ATTRIBUTES: SeededAttribute[] = [
   {
     key: 'enabled',
     text: `${ENABLED_SEED_COMMENT}
@@ -105,7 +214,11 @@ export function parseComplianceConfig(text: string): ComplianceConfig {
   const compliance = controls.compliance
 
   const problems = new Problems()
-  problems.unknownKeys(compliance, ['enabled', 'registry', 'trees', 'inputs', 'license'], '')
+  problems.unknownKeys(
+    compliance,
+    ['enabled', 'registry', 'trees', 'inputs', 'license', 'root', 'limits', 'markdown', 'lockfiles', 'directory-ratchet'],
+    '',
+  )
 
   // Absent is the documented default, never an error: install seeds only `version`
   // and `enabled`, and `registry`/`trees` both have working defaults. Present but the
@@ -127,6 +240,18 @@ export function parseComplianceConfig(text: string): ComplianceConfig {
   }
 
   const config: ComplianceConfig = { enabled, registry, trees, inputs, declarations }
+  // Assigned only when declared: an `undefined`-valued key would still change the
+  // shape every whole-object comparison of a root-less repository sees.
+  if (compliance.root !== undefined) config.root = parseRoot(compliance.root, problems)
+  if (compliance.limits !== undefined) config.limits = parseLimits(compliance.limits, problems)
+  if (compliance.markdown !== undefined) config.markdown = parseMarkdown(compliance.markdown, problems)
+  if (compliance.lockfiles !== undefined) {
+    config.lockfiles = parseLockfiles(compliance.lockfiles, problems)
+    rejectSupersededInputs(config.lockfiles, inputs, problems)
+  }
+  if (compliance['directory-ratchet'] !== undefined) {
+    config.directory_ratchet = parseDirectoryRatchet(compliance['directory-ratchet'], problems)
+  }
   if (problems.list.length > 0) {
     throw new Error(`${CONFIG_REL} is invalid:\n  - ${problems.list.join('\n  - ')}`)
   }
@@ -193,6 +318,289 @@ function parseTrees(
   return trees
 }
 
+/**
+ * A root entry is a NAME directly under the repository root, and the whole list
+ * travels to the engine as ONE comma-separated `--declare root-files=a,b` value.
+ * So a name may not contain `,` (it would split into two names), `=` (it collides
+ * with `--declare name=value`'s own separator) or `/` and `..` (a root name is not
+ * a path: either would escape the root or reach below it). Empty and
+ * whitespace-only names are refused because the engine rejects an empty item.
+ */
+const ROOT_NAME_FORBIDDEN = /[,/=]|\.\./
+
+function parseRoot(value: unknown, problems: Problems): RootDeclaration {
+  const root: RootDeclaration = { files: [], dirs: [] }
+  if (!isTable(value)) {
+    problems.add('root must be a table')
+    return root
+  }
+  problems.unknownKeys(value, ['files', 'dirs'], 'root.')
+  for (const key of ['files', 'dirs'] as const) {
+    const list = value[key]
+    if (list === undefined) continue
+    if (!Array.isArray(list)) {
+      problems.add(`root.${key} must be an array of strings`)
+      continue
+    }
+    list.forEach((item: unknown, index) => {
+      const label = `root.${key}[${index}]`
+      if (typeof item !== 'string') problems.add(`${label} must be a string`)
+      else if (item.trim() === '') problems.add(`${label} must not be empty`)
+      else if (ROOT_NAME_FORBIDDEN.test(item)) problems.add(`${label} must not contain ',', '/', '=' or '..'`)
+      else root[key].push(item)
+    })
+  }
+  return root
+}
+
+const LIMIT_KEYS = ['scripts_direct_files', 'open_gaps', 'open_plans', 'docs_pages_per_directory'] as const
+
+/**
+ * Each limit travels to the engine as `--declare <name>=N` (`scripts-direct-files`,
+ * `open-gaps`, `open-plans`, `docs-pages-per-directory`) and the engine refuses
+ * anything but a base-10 positive integer, so the same set is refused here,
+ * naming the key. A TOML float with an integral value (`20.0`) reaches this
+ * point as the number 20 — the parser does not keep the distinction — and is
+ * accepted as 20.
+ */
+function parseLimits(value: unknown, problems: Problems): LimitsDeclaration {
+  const limits: LimitsDeclaration = {}
+  if (!isTable(value)) {
+    problems.add('limits must be a table')
+    return limits
+  }
+  problems.unknownKeys(value, [...LIMIT_KEYS], 'limits.')
+  for (const key of LIMIT_KEYS) {
+    const limit = value[key]
+    if (limit === undefined) continue
+    if (typeof limit !== 'number' || !Number.isSafeInteger(limit) || limit < 1) {
+      problems.add(`limits.${key} must be a positive integer`)
+    } else {
+      limits[key] = limit
+    }
+  }
+  return limits
+}
+
+/**
+ * A markdown root is a repository-relative DIRECTORY, and the whole list travels to the
+ * engine as ONE comma-separated `--declare markdown-roots=a,b` value. So an entry may not
+ * contain `,` (it would split into two roots) or `=` (it collides with `--declare
+ * name=value`'s own separator), may not be absolute, and may not carry a `.`, `..` or
+ * empty path segment -- none of those names a directory this repository owns, and the
+ * engine refuses them as could-not-run because a declared root can only WIDEN LAY-006's
+ * allowlist. Surrounding whitespace and trailing `/` are normalised away, the same way
+ * the engine reads the comma list.
+ */
+const MARKDOWN_ROOT_FORBIDDEN = /[,=]/
+
+function parseMarkdown(value: unknown, problems: Problems): MarkdownDeclaration {
+  const markdown: MarkdownDeclaration = { roots: [] }
+  if (!isTable(value)) {
+    problems.add('markdown must be a table')
+    return markdown
+  }
+  problems.unknownKeys(value, ['roots'], 'markdown.')
+  const list = value.roots
+  if (list === undefined) return markdown
+  if (!Array.isArray(list)) {
+    problems.add('markdown.roots must be an array of strings')
+    return markdown
+  }
+  list.forEach((item: unknown, index) => {
+    const label = `markdown.roots[${index}]`
+    if (typeof item !== 'string') {
+      problems.add(`${label} must be a string`)
+      return
+    }
+    const trimmed = item.trim()
+    if (trimmed === '') {
+      problems.add(`${label} must not be empty`)
+      return
+    }
+    const root = trimmed.replace(/\/+$/, '')
+    const notADirectory = trimmed.startsWith('/') || root.split('/').some((part) => part === '' || part === '.' || part === '..')
+    if (MARKDOWN_ROOT_FORBIDDEN.test(root) || notADirectory) {
+      problems.add(
+        `${label} must be a repository-relative directory without a leading '/', a '.', '..' or empty segment, ',' or '='`,
+      )
+      return
+    }
+    markdown.roots.push(root)
+  })
+  return markdown
+}
+
+/**
+ * The two ecosystems REP-002 grades, with the file name every manifest entry must end in
+ * and the per-gate inputs a declared pair supersedes.
+ */
+const LOCKFILE_HALVES = [
+  {
+    manifests: 'bun_manifests',
+    lockfiles: 'bun_lockfiles',
+    manifestName: 'package.json',
+    inputs: ['REP-002:bun_lock'],
+  },
+  {
+    manifests: 'cargo_manifests',
+    lockfiles: 'cargo_lockfiles',
+    manifestName: 'Cargo.toml',
+    inputs: ['REP-002:cargo_lock', 'REP-002:cargo_manifest', 'REP-002:workspace'],
+  },
+] as const
+
+/**
+ * Entries travel to the engine as ONE comma-separated `--declare` value, so `,` would split
+ * one path in two and `=` collides with `--declare name=value`'s own separator. A backslash,
+ * `<`, `>`, `{` and `}` are not path characters here: a `<tree>` placeholder, a brace union
+ * and a leading `!` negation are scope SYNTAX, and an entry that carried one would mean more
+ * or less than the repository wrote. The engine refuses the same set as could-not-run.
+ */
+const LOCKFILE_ENTRY_FORBIDDEN = /[,=\\<>{}]/
+const LOCKFILE_GLOB_CHARS = /[*?[\]]/
+
+/** Is `entry` NOT a path REP-002 can scan? `manifestName` is null for a lockfile entry (a literal path). */
+function lockfileEntryRefused(entry: string, manifestName: string | null): boolean {
+  if (LOCKFILE_ENTRY_FORBIDDEN.test(entry) || entry.startsWith('/') || entry.startsWith('!')) return true
+  const segments = entry.split('/')
+  if (segments.some((part) => part === '' || part === '.' || part === '..')) return true
+  if (manifestName !== null) return segments[segments.length - 1] !== manifestName
+  return LOCKFILE_GLOB_CHARS.test(entry)
+}
+
+// A ceiling path is repository-relative and travels to the engine INSIDE one
+// comma-separated `--declare directory-ceilings=<path>:<n>,...` value, so it
+// may not contain `,` (the list separator), `:` or `=` (collisions with the
+// entry and declare separators), a leading `/` or `!`, or a `.`, `..` or empty
+// segment — none of those names a tree this repository owns, and the engine
+// refuses them as could-not-run.
+const CEILING_PATH_FORBIDDEN = /[,:=]/
+
+/**
+ * `[controls.compliance.directory-ratchet]`: LAY-004's configured ceilings.
+ * The engine reads each `<path>:<n>` entry with the same base-10 positive
+ * integer rule as the limits, so the same set is refused here, naming the
+ * path.
+ */
+function parseDirectoryRatchet(value: unknown, problems: Problems): DirectoryRatchetDeclaration {
+  const ratchet: DirectoryRatchetDeclaration = { max_children: {} }
+  if (!isTable(value)) {
+    problems.add('directory-ratchet must be a table')
+    return ratchet
+  }
+  problems.unknownKeys(value, ['max_children'], 'directory-ratchet.')
+  const ceilings = value.max_children
+  if (ceilings === undefined) return ratchet
+  if (!isTable(ceilings)) {
+    problems.add('directory-ratchet.max_children must be a table')
+    return ratchet
+  }
+  for (const [path, ceiling] of Object.entries(ceilings)) {
+    const label = `directory-ratchet.max_children.${path}`
+    if (typeof ceiling !== 'number' || !Number.isSafeInteger(ceiling) || ceiling < 1) {
+      problems.add(`${label} must be a positive integer`)
+      continue
+    }
+    if (CEILING_PATH_FORBIDDEN.test(path) || path.startsWith('/') || path.startsWith('!')) {
+      problems.add(`${label} must be a repository-relative path without a leading '/' or '!', or any of ',', ':', '='`)
+      continue
+    }
+    if (path.split('/').some((part) => part === '' || part === '.' || part === '..')) {
+      problems.add(`${label} must be a repository-relative path without a '.', '..' or empty segment`)
+      continue
+    }
+    ratchet.max_children[path] = ceiling
+  }
+  return ratchet
+}
+
+function parseLockfiles(value: unknown, problems: Problems): LockfilesDeclaration {
+  const lockfiles: LockfilesDeclaration = { bun_manifests: [], bun_lockfiles: [], cargo_manifests: [], cargo_lockfiles: [] }
+  if (!isTable(value)) {
+    problems.add('lockfiles must be a table')
+    return lockfiles
+  }
+  problems.unknownKeys(value, [...LOCKFILE_KEYS], 'lockfiles.')
+  for (const half of LOCKFILE_HALVES) {
+    const broken = new Set<string>()
+    for (const [key, manifestName] of [
+      [half.manifests, half.manifestName],
+      [half.lockfiles, null],
+    ] as const) {
+      const list = value[key]
+      if (list === undefined) continue
+      if (!Array.isArray(list)) {
+        problems.add(`lockfiles.${key} must be an array of strings`)
+        broken.add(key)
+        continue
+      }
+      const seen = new Map<string, number>()
+      list.forEach((item: unknown, index) => {
+        const label = `lockfiles.${key}[${index}]`
+        if (typeof item !== 'string') {
+          problems.add(`${label} must be a string`)
+          broken.add(key)
+          return
+        }
+        const entry = item.trim()
+        if (entry === '') {
+          problems.add(`${label} must not be empty`)
+          broken.add(key)
+          return
+        }
+        if (lockfileEntryRefused(entry, manifestName)) {
+          problems.add(
+            manifestName === null
+              ? `${label} must be a literal repository-relative file path without a leading '/' or '!', a '.', '..' or empty segment, a glob character ('*', '?', '[', ']'), or any of ',', '=', '\\', '<', '>', '{', '}'`
+              : `${label} must be a repository-relative path or glob ending in ${manifestName}, without a leading '/' or '!', a '.', '..' or empty segment, or any of ',', '=', '\\', '<', '>', '{', '}'`,
+          )
+          broken.add(key)
+          return
+        }
+        const first = seen.get(entry)
+        if (first !== undefined) {
+          problems.add(`${label} duplicates lockfiles.${key}[${first}]`)
+          broken.add(key)
+          return
+        }
+        seen.set(entry, index)
+        lockfiles[key].push(entry)
+      })
+    }
+    // A half is declared as a pair. One list without the other would leave the engine
+    // guessing which default the missing list takes, and the engine refuses it too. Skipped
+    // when either list already has a problem: that is the one to fix first.
+    const hasManifests = lockfiles[half.manifests].length > 0
+    const hasLockfiles = lockfiles[half.lockfiles].length > 0
+    if (hasManifests !== hasLockfiles && !broken.has(half.manifests) && !broken.has(half.lockfiles)) {
+      const [present, missing] = hasManifests ? [half.manifests, half.lockfiles] : [half.lockfiles, half.manifests]
+      problems.add(`lockfiles.${present} is declared without lockfiles.${missing}: a half is declared as a pair`)
+    }
+  }
+  return lockfiles
+}
+
+/**
+ * `REP-002:<name>` inputs are the per-gate overrides a declared pair supersedes: the engine
+ * grades a declared half from its declaration and never consults them. Left in place they
+ * would be silently ignored, so the combination is refused.
+ */
+function rejectSupersededInputs(
+  lockfiles: LockfilesDeclaration,
+  inputs: Record<string, string>,
+  problems: Problems,
+): void {
+  for (const half of LOCKFILE_HALVES) {
+    if (lockfiles[half.manifests].length === 0 || lockfiles[half.lockfiles].length === 0) continue
+    for (const input of half.inputs) {
+      if (input in inputs) {
+        problems.add(`inputs.${input} is superseded by lockfiles.${half.lockfiles}; remove the input`)
+      }
+    }
+  }
+}
+
 export function loadComplianceConfig(repo: string): ComplianceConfig {
   const path = join(repo, CONFIG_REL)
   if (!existsSync(path)) throw new Error(`${CONFIG_REL} is missing — ${INSTALL_HINT}`)