subprojects

name	subprojects
description	Enumerate scannable sub-folders inside a repository. Identifies monorepo packages, workspaces, and discrete modules so the analyst can scope deep-dive scans to a specific sub-path instead of treating a huge tree as one unit. Runs at repo level; writes back a list that surfaces on the repo overview.
license	MIT
compatibility	Needs network access to the scrutineer API only for logging; the enumeration itself is filesystem-only against ./src.
metadata	{"scrutineer.version":1,"scrutineer.output_file":"report.json","scrutineer.output_kind":"subprojects"}

subprojects

List the discrete scannable units inside a repository so the analyst can scope security scans to a sub-path instead of the whole tree. A repository with a single package at the root gets an empty list — that is the expected shape for the common case. A monorepo like apache/airflow or kubernetes/kubernetes gets a row per sub-package.

Workspace

• ./src — the repository at HEAD. Read-only.
• ./context.json — has scrutineer.api_base, scrutineer.token, scrutineer.repository_id. Not finding-scoped, not sub-path-scoped (this skill produces sub-paths; it does not consume one).
• ./report.json — write the enumeration here.
• ./schema.json — output shape.

How to identify subprojects

A subproject is a sub-folder that looks like an independently buildable, scannable unit. Heuristics, in descending order of signal strength:

1. Explicit monorepo declarations. If the repo has any of these at the root, the file names the workspaces directly. Expand any globs against ./src and emit one row per matched directory:

   • pnpm-workspace.yaml — packages: glob list
   • lerna.json — packages: array
   • nx.json / workspace.json — NX workspace layout
   • turbo.json alongside a root package.json with a workspaces field
   • go.work — use (...) list
   • root Cargo.toml with [workspace].members
   • pyproject.toml with [tool.uv.workspace].members or Rye/hatch equivalents

2. Sub-folder package manifests. Scan sub-folders (depth ≤ 3, skip node_modules, vendor, .git, dist, build, target) for any of the manifests below. Run this even when a workspace declaration exists, then union the two sets — go.work and friends are often incomplete.

   • go.mod → go-module
   • package.json with a name field → npm-package
   • pyproject.toml / setup.py / setup.cfg → python-package
   • Cargo.toml with [package] → rust-crate
   • composer.json → composer-package
   • pom.xml or build.gradle[.kts] → maven/gradle-module
   • Gemfile and/or *.gemspec → ruby-gem
   • Package.swift → swift-package
   • Dockerfile alongside a README in a services/ or apps/ tree → service

3. Cluster by top-level directory. If heuristic 2 produces many hits under a common parent (e.g. providers/amazon, providers/google each has its own pyproject.toml), keep each sub-folder as its own row rather than rolling them up — an analyst may want to scan just one cloud provider's code.

What NOT to emit

• The root as a subproject. A repo with one package at the root has zero subprojects; scrutineer already treats root as the default scan scope.
• Test fixtures, examples, vendored deps. Folders called testdata/, fixtures/, examples/, vendor/, third_party/, external/ almost always ship code that is not the project itself — skip them.
• Build outputs. dist/, build/, out/, target/, node_modules/, .venv/, __pycache__/ — same.
• Nested workspaces with no independent manifest. If a sub-folder has no manifest and is not named by a workspace declaration, it is not a subproject; it is just a sub-folder.

Output

Write ./report.json:

{
  "subprojects": [
    {
      "path": "airflow-core",
      "name": "airflow-core",
      "kind": "python-package",
      "description": "Core Airflow scheduler, webserver, and DAG runtime."
    },
    {
      "path": "airflow-ctl",
      "name": "airflow-ctl",
      "kind": "python-package",
      "description": "Airflow CLI distributed as a separate package."
    },
    {
      "path": "providers/amazon",
      "name": "apache-airflow-providers-amazon",
      "kind": "python-package",
      "description": "AWS provider package. Ships operators, hooks, and sensors for S3, EMR, Glue, and other AWS services."
    }
  ]
}

Fields:

• path — required, relative to repo root, no leading slash. This is what scrutineer stores on Scan.sub_path when the analyst scans it.
• name — short human label. Use the package's own name when the manifest has one (name in package.json, module path in go.mod, [package].name in Cargo.toml); otherwise the last segment of path.
• kind — the detection hit: go-module, npm-package, python-package, rust-crate, composer-package, maven-module, gradle-module, ruby-gem, swift-package, service, etc. Free-form; the UI renders it as a badge.
• description — one or two sentences. Read the README in the sub-folder if present, or infer from the package name and directory structure. Keep it specific ("AWS provider package", not "code for AWS").

Constraints

• Empty list is the correct output for a single-package repo. Do not invent subprojects to avoid an empty array.
• Do not include the root directory as a row. Root is implicit.
• Do not add more than ~50 rows. If a monorepo is bigger than that, keep workspace-declared entries first, then fill the remainder by file count (largest first), and set the top-level notes field to "truncated to 50 of N".
• Scrutineer replaces the full set on each re-run, so missing rows from a previous run will disappear — do not try to merge with prior output.