Skip to content

Component Autodetect ​

The algorithm by which aburi init and aburi scan (when the config declares no components[]) infer logical Components from the physical structure of a monorepo. If the config explicitly declares components[], it takes precedence over the autodetect result (config.md §6.1).

References:

  • ir-schema.md §4 — Component structure
  • config.md §6 / §12 — Component override / autodetect overview

1. Purpose ​

Aburi infers "which set of files forms one logical unit (Component)" with zero user input.

This enables:

  • aburi init to generate aburi.json with pre-populated components[]
  • aburi scan to find Components a config does not declare
  • Newcomers to get an overview of the workspace structure before writing any config

2. Two-stage algorithm ​

1. Workspace root detection
   - Walk upward from the CLI execution cwd
   - Take the first `.git` as root, or the outermost workspace marker when there is none

2. Component extraction
   - Run each detector in parallel from the root
   - Merge and dedupe detection results
   - Fill in id / name / languages / frameworks / publicApi / description via inference rules

2.1 Workspace root detection ​

Walk from cwd toward parents. The workspace root is the first directory holding a .git — a directory, or a file opening with gitdir:, the pointer a linked worktree or a submodule has in its place. Below it, or when the walk reaches the filesystem root without meeting one, the root is the outermost (closest to the filesystem root) directory in which any of the following is found:

  • .git, as above
  • pnpm-workspace.yaml
  • turbo.json
  • nx.json
  • lerna.json
  • go.work
  • Cargo.toml (containing a [workspace] section)
  • pyproject.toml (containing [tool.uv.workspace] / [tool.hatch.workspaces] / [tool.poetry])
  • package.json (containing a workspaces field)
  • .aburi-workspace (reserved for future use, Aburi-specific marker)

If markers are found at multiple levels, the outer one wins: a sub-project's package.json inside a monorepo does not shrink the workspace to that sub-project. The walk does not go past a .git, so a repository nested under another marker is a workspace of its own (§11.1).

A working tree whose repository is kept elsewhere, under GIT_DIR or with GIT_WORK_TREE naming a tree away from the .git git finds, has no .git at its top. While either variable is set, the CLI asks git for the top with git rev-parse --show-toplevel, run in the directory aburi runs in, and the walk follows the answer:

  • A top that GIT_WORK_TREE or core.worktree names is a root the walk stops at as it does at a .git. The walk meets it as the ancestor of the start whose real path is the top's, however links spell either. A .git between the start and the top still stops the walk first: it is a repository of its own, such as the base worktree aburi diff checks out under a TMPDIR inside the working tree. A start none of whose ancestors is the top, one outside the tree or one reached through a link from outside it, walks as if git had not answered.
  • With neither set, which git is asked through git config --get core.worktree, git takes the directory it runs in as the top, and so does the walk, unless it meets a .git above that directory: a hook exports GIT_DIR, and run from a package directory below its .git, git's answer is only that package.
  • A bare repository has no working tree, and git refuses there as it does outside a repository. The walk then goes on as it would without the variables, and so it does when git cannot be run.

detectWorkspaceRoot takes git's answer as workTree, { top } or "start", and spawns nothing.

2.2 Component extraction ​

Each detector receives the workspace root and determines whether a marker it can handle exists. If so, it returns zero or more "workspace candidates".

detector.detect(workspaceRoot) → {
  manager: WorkspaceManager  // tool name + roots
  workspaces: Workspace[]
} | null

All detector results are merged, duplicates with the same path are removed, and each workspace is then converted into a Component.

3. Detectors ​

3.1 JS/TS ecosystem ​

DetectorMarkerWorkspace extraction method
pnpmpnpm-workspace.yamlResolve the globs in the packages: field
npm/yarnworkspaces in package.jsonResolve globs from the array or {packages: [...]}
bunSame as above (npm-compatible)Same as above
turboturbo.jsonTreated as a monorepo hint. Actual workspaces come from pnpm/npm detectors
nxnx.json + project.jsonEvery directory containing a project.json that .gitignore does not exclude (§8)

3.1.1 Glob resolution conventions ​

  • POSIX globs (forward slashes)
  • Relative to the workspace root
  • A pattern names a directory that holds the manifest, and is resolved against the manifest: p is matched as p/package.json (a trailing slash replaced), and the directory holding each match is the candidate. This is how pnpm and npm resolve these patterns, and the nx detector finds a directory by its project.json the same way — though, unlike these patterns, its search does not follow links (below). Three consequences worth stating:
    • . and ./ name the workspace root itself, and nothing else. Matched as a directory instead, . is a pattern that reaches every directory in the workspace.
    • A literal path names that directory, not its subtree.
    • A matched directory with no manifest is not a package, and is not a candidate.
  • A negated pattern (!packages/legacy) takes the same transform and removes the package it names
  • An empty pattern declares nothing
  • package.json is the only manifest recognized. pnpm also accepts package.yaml and package.json5, and globs package.{json,yaml,json5}; a package declared in either is not detected here, because the manifest is parsed as JSON for the id, name, frameworks and public API. Supporting them is a parser change, not a resolution one.
  • Which resolved directories become Components is §5's rule, not the manager's. pnpm counts the workspace root as a workspace project unconditionally — "The root package is always included, even when custom location wildcards are used" — and a pattern naming it changes nothing for pnpm. Here it does: the root is a Component when a pattern names it, and otherwise only through §5's no-detector fallback. A root Component's roots: ["."] contains every other component's root, so making one unconditionally would give every workspace a component whose census covers the whole tree.
  • Links are followed, as pnpm and npm follow them: pnpm ls -r lists a package reached through a directory link at the link's path as well as at its own. A pattern matching such a link makes the package at the link's path a candidate, and so a Component. Discovery does not follow links (§8), so that Component owns no scanned file and shows as a 0 row in the workspace table — the same report §12 gives any component that fails closed. The nx detector's search for project.json does not follow them (§8)
  • A wildcard does not match a name that starts with a dot, as pnpm's and npm's resolution does not: packages/* passes over packages/.template, while a pattern that spells the dot (.github/actions/*) reaches .github/actions/deploy. Discovery and the nx detector's search for project.json walk dot directories (§8), so a package such a pattern does not declare is not a Component even where its files are scanned, unless another detector finds it: with nx.json present, packages/.template/project.json makes packages/.template a Component whatever packages/* says, because the detectors' results are merged
  • A package whose directory has no Document spelling is not a candidate. A name holding a backslash, or a top-level name opening with one ASCII letter and : (a:pkg), cannot be a roots entry (ir-schema.md §14 #10), so the package is neither a Component nor on managers[].roots, for the nx detector as for these patterns. It is not outside the workspace either, so detection does not stop: the rest of the workspace is detected and scanned. Detection reports the package instead — the tool, the manifest of the detector that found it, the directory and the segment to rename, both as spelled on disk — and aburi scan (exit 3) and aburi init (exit 0) name it on stderr (cli-spec.md §5.8). Discovery lists the package's files as ones it cannot name only when a language plugin claims one of them, so without that report a package holding just its package.json and a README would leave no trace. Its pattern did name a package, so it is not one that named none (§5). A root relative gives as absolute is the other thing — a package on another Windows drive, which is outside — and is refused as .. is; and a root under .. is refused whatever its name, since a backslash or a drive further down does not bring it inside
  • Maximum depth of ** is 10 (to avoid false positives)
  • A path matching multiple globs counts as a single entry
  • Anything under node_modules/ is always excluded

3.2 Go ecosystem ​

DetectorMarkerWorkspace extraction method
gogo.workEnumerate the directories in use ./module-a

If there is no go.work but a standalone go.mod, the root is a single module = a single Component.

3.3 Rust ecosystem ​

DetectorMarkerWorkspace extraction method
cargoCargo.toml with [workspace]Resolve the globs in members = [...]

If there is a standalone Cargo.toml without [workspace], the root is a single crate = a single Component.

3.4 Python ecosystem ​

DetectorMarkerWorkspace extraction method
uvpyproject.toml with [tool.uv.workspace]members = [...]
hatchpyproject.toml with [tool.hatch.workspaces]members
poetry (multi-project)Search for multiple pyproject.toml files with [tool.poetry.dependencies]Recursive detection of subdirectories

Python workspace standards are fragmented, so multiple detectors exist.

3.5 Others (planned) ​

ManagerMarkerNotes
Lernalerna.jsonOverlaps with npm/yarn detection
BazelWORKSPACE / WORKSPACE.bazel / MODULE.bazelExtract workspaces from BUILD files
Mavenpom.xml with <modules>Parent project + modules
Gradlesettings.gradle(.kts) with include(...)Included projects
Elixirmix.exs umbrella projectEverything under apps_path
Composercomposer.json (when using composer/installers)Not generalized; deferred

Currently only JS/TS detectors are implemented. For the others, the detector plugin interface is defined so that each language plugin can add detectors in a future release (§7; see the roadmap).

4. Inference of Component fields ​

Mapping from each workspace to a Component.

4.1 id ​

Priority order:

  1. package.json#name (JS/TS): fold the scope into the name and kebab-case the result (@scope/billing → scope-billing)
  2. project.json#name (nx): the project name, for a directory that has no package.json
  3. package.name in Cargo.toml (Rust)
  4. project.name in pyproject.toml (Python)
  5. Trailing segment of the module name in go.mod (Go)
  6. Kebab-case the trailing segment of the workspace directory's full path

This is a priority over sources, not a single source: neither a manifest that carries no name nor one whose name yields no id is an answer, and the next source is asked before the directory name is. @scope/ is a name §4.2 can use and §4.1 cannot, so a Component can take its id and its name from different manifests.

A directory that several detectors claim is described by all of their manifests at once (§7), and they are read in this order — by filename, so the order the detectors happened to run in cannot move an id. The package.json under a candidate's root is read whether or not a detector reported it: a directory holding one is an npm package however it was found, and nx reports only project.json.

The scope is folded in rather than discarded because it is the part of a published name that already tells two same-named packages apart, and the collision rule below cannot: in the usual layout every package sits directly under packages/, so @alpha/utils and @beta/utils collide on utils and suffix alike to utils-packages.

The fold is over the bare name's id, not over the raw string: @acme/--- yields the empty id and aborts as the rule below says, rather than kebab-casing to the scope alone and giving every unusable name in one scope the same silent id. It also erases the namespace boundary, so @foo/bar-baz, @foo-bar/baz and an unscoped foo-bar-baz are one id where the first two were distinct; that is a collision like any other and the rule below resolves it.

On collision (multiple workspaces yielding the same id) → append the parent directory name as a suffix (billing → billing-apps / billing-packages). Where that is still not enough — team1/shared/pkg and team2/shared/pkg both suffix to pkg-shared — the suffix takes one more step up the path for every id still shared, until each is unique or its root has no more ancestors (pkg-shared-team1 / pkg-shared-team2). A suffix that lands on another, already-unique id puts that id in the next round too, so it moves as well. What is left after the path runs out — two roots whose ancestor segments all kebab-case to nothing, or a group in which every member has consumed its whole path — takes a short hash of roots[0] appended to the id it reached (utils-packages-b9b98f98), every member of the group included. A root with no ancestors at all, ., is only in that position when the collision outlasts every other member's path too: . against packages/foo resolves to app / app-packages with no hash.

Two things this does and does not promise, because the difference is the whole point of the rule:

  • It never reads a component's position. The suffix is built from that component's own base id and roots[0], and how far up the path it goes is decided by the set of ids in contention — not by the order the components arrive in, and not by which of them sorted first. The positional -2, -3, … counter it replaces did exactly that: adding @alpha/utils ahead of @beta/utils and @gamma/utils demoted both of them by one, and since the id keys Symbol.component, both Dependency endpoints and cross-revision comparison, a single new package read downstream as every component having been replaced.
  • It does not promise an id never moves. A package that arrives claiming an id already in use moves whoever holds it: adding packages/x named shared-libs takes team/libs/shared from shared-libs to shared-libs-team. What has changed is the reach of that — before, any package under the same parent renumbered its neighbours; now only a package contending for the same id moves anything, and components elsewhere in the tree are untouched.

Hash suffixes separate a group by digest rather than by construction, so uniqueness is checked once on exit. A duplicate that survives — no run has produced one — aborts with component-id-collision-unresolved rather than being handed back: aburi init writes components[] without building an IR, so the §14 #2 uniqueness invariant would not be the one to catch it.

The result must satisfy aburi.ir.v1.json#/$defs/ComponentId. Names that kebab-case to the empty string — a directory whose name is entirely non-ASCII, say — cannot yield an id, and detection aborts with invalid-component-id naming the manifest or directory it came from. Declare the component explicitly in aburi.json components[] to override the derivation.

4.2 name ​

Priority order:

  1. Full name from package.json#name (including the scope, e.g. @scope/billing)
  2. The name field of other manifests, in §4.1's order
  3. The trailing segment of the workspace directory as-is (capitalized)

4.3 roots ​

A single element: the detected workspace path. POSIX path relative to the workspace root.

4.4 languages ​

Shallow-scan each component's subtree (up to 3 directory levels below its own root) and tally extension frequencies, over the files the workspace has not excluded — see §8. Include the language id for each extension exceeding the threshold (>5% and >10 files).

The census counts every extension in the table below, whether or not a lang plugin claims it. That is deliberate and is the point of the paragraph after next: the field answers "what is this component written in", not "what did this run parse", and aburi init has to answer it before any plugin is resolved. A file too large for maxFileSizeBytes counts for the same reason.

Minority-language files below the threshold are handled as follows:

  • Not included in Component.languages[] (autodetect lists primary languages only)
  • However, if the corresponding lang plugin is enabled, those files are still scanned normally and Symbols are extracted
  • "Symbols in a language not listed in Component.languages" is normal (e.g., a mostly-TS component containing a few .py scripts with the py plugin enabled)
  • Files in a language with no corresponding lang plugin are skipped with a warning (same handling as §6.5)

The role of Component.languages[] is to indicate "the primary languages needed to understand this component". It is independent of the Symbol extraction scope.

Extension mapping:

Extensionlanguage id
.ts/.mts/.ctsts
.tsxtsx
.js/.mjs/.cjsjs
.jsxjsx
.pypy
.gogo
.rsrs
.javajava
.kt/.ktskt
.scalascala
.rbrb
.phpphp
.cscs
.swiftswift
.ex/.exsex

This mapping is not fixed: it can be reverse-derived from the fileExtensions each language plugin declares (lang-plugin.md §4.1).

4.5 frameworks ​

Detect known frameworks from dependency manifests:

SourceDetection pattern → framework id
package.json deps/devDeps@nestjs/core → nestjs
Same as abovenext → nextjs
Same as abovereact (with react-dom) → react
Same as abovevue → vue
Same as aboveexpress → express
Same as abovefastify → fastify
Same as abovekoa → koa
Same as abovehono → hono
Same as aboveastro → astro
Same as abovesvelte (kit/dev) → svelte
Same as abovesolid-js → solid
Same as above@trpc/server → trpc
go.modgithub.com/gin-gonic/gin → gin
Same as abovegithub.com/labstack/echo → echo
Same as abovegithub.com/gofiber/fiber → fiber
pyproject.toml depsdjango → django
Same as abovefastapi → fastapi
Same as aboveflask → flask

The list is owned by the Aburi core, but a mechanism is planned whereby a framework plugin, once it declares its name in manifest.provides.frameworks[], can extend the "detection pattern → name" mapping on the plugin side (see the roadmap). Today the fixed core list is used.

Detected frameworks are only recorded in Component.frameworks[]; the corresponding plugin is not auto-enabled (config.md §15.1).

4.6 publicApi ​

Read the paths package.json names:

jsonc
// packages/sdk/package.json
{
  "exports": {
    ".": "./src/index.ts",
    "./client": "./src/client.ts"
  }
}

→

jsonc
{
  "roots": ["packages/sdk"],
  "publicApi": ["packages/sdk/src/client.ts", "packages/sdk/src/index.ts"]
}

Every string target of exports, through conditions and arrays, and main, module, types and typings are read, whether or not exports is present; the entries are their union, deduplicated and sorted.

Each value is a path relative to the package directory, and its entry is that path written from the workspace root, as roots[] and every Symbol id are: the component's root, then the value in one spelling. That spelling is NFC, with no leading ./ however often it repeats, and no . or empty segment inside it, so ././src/index.ts, ./src/./index.ts and src//index.ts in packages/sdk/package.json are all packages/sdk/src/index.ts. A package at the workspace root (root .) adds no prefix: its entry is src/index.ts. These values contribute no entry:

  • the package directory itself: "", ".", "./", "./.". "main": "./" is a legal npm value (it resolves to ./index.js), and "./": "./" is the folder-mapping form of exports that Node accepted before subpath patterns
  • any other directory, which is a value whose last segment is empty or .: "./lib/", "./lib/.", or the target of a folder mapping such as "./lib/": "./lib/"
  • an absolute path ("/", "/dist/index.js"), one whose first segment reads as a Windows drive ("C:/dist/index.js", "a:index.js", though "ab:index.js" is kept), or one holding a .. segment, even "./src/../index.js", which stays inside the package: an entry is the value's own spelling, never a path resolved from it
  • a value holding a backslash, which a Document cannot spell (ir-schema.md §14 #10)
  • a value that is not a string, such as "main": 42

An entry is the file the manifest names, not a file a resolver would find for it. index.js inside a directory is Node's lookup, and a folder mapping exports whatever the directory holds at the time; neither is a path the manifest wrote. An empty entry in particular would be no glob at all, and the schema refuses it.

Detection reports every string value on that list beside the Components, by component id and then in the order its manifest holds them, naming the component, the manifest, where in it the value sits (main, or a place in exports such as exports["./lib/"] or exports["."]["import"][0]), the value and which of the cases above it is. A value that fits more than one case is reported under the first that applies, in this order: an absolute path, the package directory, another directory, a first segment that reads as a drive or a backslash, then a .. segment. So "/lib/" is an absolute path, "../" and "C:/" are directories, and between a drive and a backslash the backslash wins only when it sits in the first segment itself: "C:\\x" is a backslash, "C:/..\\x" a drive. aburi scan writes one line on stderr for each (cli-spec.md §5.6), since a value that gives no entry otherwise leaves the IR looking like that of a package that declared nothing. A value that is not a string is not reported: null is how exports keeps a subpath private, and a number names no path at all.

If no value gives an entry, the publicApi key is omitted — it is Class B under ir-schema.md §1.1, so "no public surface declared" is spelled as an absent key, never as []. frameworks follows the same rule; description is Class A and is written as an explicit null when detection has nothing to put there.

For Python / Go / Rust, each language plugin will provide "public API file" inference logic in a future release (see the roadmap). Today only JS/TS is covered.

5. Single project (non-monorepo) ​

If no detector hits, the workspace root is treated as a single Component:

jsonc
{
  "id": "<inferred from package.json name>",   // or the workspace root's directory name
  "name": "<same as above>",
  "roots": ["."]
}

This lets Aburi work even for the smallest single-project setups (e.g., a standalone TypeScript repository).

"No detector hits" means no candidate directory, not no marker. A manifest that parsed and declared no package reaches the same fallback, and there are two ways to get there:

  • A pnpm-workspace.yaml whose packages: field is absent or empty, or a package.json with no workspaces. pnpm reads the first the same way — "If the packages field is omitted, only the root package is included in the workspace" — and an empty list identically, so the whole repository as one Component is the right answer.
  • Patterns that matched nothing: a mistyped pattern, a monorepo with no packages in it yet, or packages whose manifest is one §3.1.1 does not recognize. The whole repository becomes one Component, which is the wrong answer for a workspace that declared packages — so detection reports it and aburi scan and aburi init name it on stderr. One entry per manifest, not per manager: pnpm-lock.yaml beside a package.json#workspaces makes both manifests spell pnpm, so the manifest path is what identifies the file to open and what orders two reports. The IR itself keeps no trace a reader can act on: workspace.managers[].roots is empty, which is also what a turbo co-marker writes on purpose.

A workspace whose only packages sit in directories with no Document spelling (§3.1.1) reaches the fallback as well, since none of them is a candidate. Its patterns did name packages, so they are not reported as patterns that named none; each package is reported instead, and aburi scan and aburi init follow those lines with the fallback's, worded No other workspace package was found since one was.

A third shape does not reach the fallback at all. A packages: or workspaces that is present and is not a list of strings — a trailing colon making the entry a map, a bare scalar, a number in the list — is refused with workspace-manifest-malformed naming the manifest and the entry. pnpm refuses all three itself, the remedy differs from a dead pattern's (write it as a list, rather than fix the pattern), and filtering the element away quietly would put every package the manifest meant to declare on the fallback with nothing said.

6. Detector extension mechanism ​

Language plugins can provide additional detectors:

ts
interface ComponentDetector {
  id: string                                 // "uv", "cargo", "go-work", etc.
  detect(workspaceRoot: string): DetectorResult | null
}

interface DetectorResult {
  manager: WorkspaceManager                  // an element of workspace.managers[] per ir-schema §2
  workspaces: WorkspaceCandidate[]
}

interface WorkspaceCandidate {
  root: string                               // path relative to workspace root
  manifestPath: string                       // path to package.json, etc.
  rawMetadata: unknown                       // raw parse result of the manifest (aids Component inference)
}

Allowing each language plugin's manifest.provides to include a detector is a planned extension (see the roadmap); today the fixed core detector set is used.

6.5 Handling mixed languages/runtimes ​

A monorepo mixing multiple managers, such as apps/web (pnpm) + apps/api (cargo) + services/ml (uv), lets each detector hit independently.

  • Record all detected tools in workspace.managers[] (e.g. [{tool:"pnpm",...}, {tool:"cargo",...}, {tool:"uv",...}])
  • Each workspace becomes a Component under its own manager's naming conventions
  • Each Component's languages is determined automatically by scanning its subtree (§4.4)
  • Since only TS is supported today, when a non-TS workspace is detected:
    • The Component is still created (to preserve the full architectural picture)
    • The language is included in languages, but Symbol extraction is skipped
    • Recorded in stats.skippedFiles[] with reason: "unroutable" — that reason covers both ways a file has no route into the Document, and here it is the first: no loaded plugin claims the extension (to be revisited when more languages land — see the roadmap)
    • Warning on stderr: Component <id> has language <lang> but no lang plugin enabled. Symbols not extracted.

7. Conflict resolution ​

When multiple detectors return the same path (e.g., both pnpm and turbo detect packages/billing):

  • Merge into one workspace candidate (dedupe by path)
  • Record manager information from both (two entries in workspace.managers[])
  • Two manifests that spell one tool — pnpm-workspace.yaml and a package.json#workspaces beside pnpm-lock.yaml — give that tool one entry in workspace.managers[], holding every root either declares, and each directory one candidate
  • A single Component
  • Keep every manifest the detectors found for that directory, plus the package.json under its root whether or not one of them reported it, and read them in §4.1's order for id and name. A directory claimed by pnpm and nx at once has a package.json and a project.json, and they routinely name it differently: the first is the published npm name the rest of the Document is written against, the second an nx project name
  • A manifest that is present and cannot be read — bad JSON, or an IO failure that is not "no such file" — aborts detection with workspace-manifest-malformed naming the file. Absent is the ordinary case and says nothing; unreadable is an identity this run cannot see, and answering with the next manifest's name would hide it
  • One byte order mark (U+FEFF) opening a manifest is read past, in every manifest detection reads — a candidate's package.json or project.json, the root package.json and pnpm-workspace.yaml, and the markers §2.1's walk opens, Cargo.toml and pyproject.toml included. PowerShell 5's Out-File and Set-Content write one under -Encoding utf8, and in a JSON manifest Node's require(), npm and pnpm read past it, as RFC 8259 §8.1 allows. In a JSON manifest, a second one or one after the first character is bad JSON, and the message names the parser's detail, or says the file opens with more than one mark: an editor that hides them shows valid JSON
  • frameworks (§4.5) and publicApi (§4.6) are read from the package.json alone. They are defined over dependencies and exports, which are npm's fields; an nx project.json holds targets whose options are arbitrary JSON, so a key of either name in one is not the npm field it resembles

When multiple detectors generate the same id with different paths (§4.1):

  • Append suffixes per the collision-avoidance convention in §4.1

8. .gitignore / exclusions ​

  • Honour .gitignore per config.respectGitignore, by the rules in drop-list.md §3.3 — every directory's file, asked about each candidate rather than folded into the traversal's exclusion globs
  • Category A's core patterns apply too, the same list discovery uses rather than a copy of part of it: node_modules/, vendor/, __pycache__/, out/, .venv/, *.d.ts and the rest of drop-list.md §3.1
  • config.ignore[] and the loaded language plugins' file-drop globs apply when the caller has them. The census is one walk from the workspace root, bucketed by component root afterwards, because those patterns are workspace-root relative by contract and cannot be matched against a walk rooted inside a package
  • The one caller that has neither is aburi init, which detects components in order to write the first config. It honours .gitignore and the core patterns, which is everything knowable before a config exists
  • Dot directories: the language census and the nx detector's search for project.json walk them, as discovery does (drop-list.md §3), so a dot directory's files count towards its component's languages and an nx project kept in one is a Component, as nx itself finds it. The resolution of declared package patterns reads a leading dot as the package manager does (§3.1.1)
  • Another checkout: the language census and the nx detector's search for project.json list nothing in a directory below the workspace root that holds a .git, a directory or a gitdir: pointer, as discovery lists nothing there (drop-list.md §3): its files are not the outer checkout's, so they count towards no language, and an nx project in it would own no scanned file. The resolution of declared package patterns walks into it, as pnpm and npm do (§3.1.1)
  • Symlinks: of detection's three filesystem searches, two do not follow them and one does. The language census and the nx detector's search for project.json do not, because discovery does not (drop-list.md §3): a file only a link reaches is never scanned, so it does not count towards a language, and a project only a link reaches would be a Component no scanned file belongs to. The resolution of declared package patterns (pnpm, npm, yarn, bun) does, as the package manager does (§3.1.1), so a package declared through a link is a Component that owns no scanned file
  • A directory one of the three searches cannot list ends detection, naming it, by discovery's rule (drop-list.md §3): one gone by the time it is listed is passed over, and any other failure ends the run, apart from the .gitignore exemption below. For the census the files under such a directory would go uncounted. For the detectors a manifest under it is a package this run cannot see — §7 already refuses to answer around a manifest that is there and cannot be read, and a directory that cannot be listed hides every manifest below it, whether the failure is a permission or a descriptor table that ran out for one directory and not the next. A link the resolution of declared package patterns follows and cannot resolve ends detection the same way, naming the link; one that dangles or loops (ENOENT, ELOOP) is what the commit holds, so every checkout passes it over alike
  • .gitignore reaches each search as it reaches the tool the search stands for. The census and the nx detector's search for project.json honour it while config.respectGitignore holds: the census counts no git-ignored file, and a project.json in a git-ignored directory is no nx project, as nx's own file walk skips what .gitignore excludes. A directory it excludes may then go unlisted, since nothing under it could count. The resolution of declared package patterns never reads it, as pnpm and npm do not: a pattern names its directories, so a package in a git-ignored one is still a package, and failing to list it ends detection whatever the setting. The detectors take no config.ignore[] and so reach directories discovery never lists, such as build/ and coverage/: one of those that cannot be listed ends detection unless the nx search alone reaches it and .gitignore excludes it
  • The contents of a .git directory are never read: every search drops a .git from the listing of the directory that holds it, at any depth and whatever its patterns spell. A .git file is read only as far as its opening gitdir: , to tell a linked worktree's or a submodule's pointer from any other file of that name. Either one ends the workspace-root walk (§2.1)

9. Performance ​

The autodetect portion of aburi init / aburi scan targets <200ms (medium-sized monorepo).

Implementation guidance:

  • Filesystem traversal is asynchronous and parallel
  • Manifest reads are memoized
  • Glob resolution uses an efficient fast-glob-style implementation

10. Verifiable properties ​

IDInputExpected
CD1pnpm-workspace.yaml: packages: ["packages/*"] + packages/{a,b,c}/package.json3 Components detected, ids from each package.json#name
CD2npm workspaces ["apps/*", "libs/*"]Every package under apps and libs becomes a Component
CD3turbo.json + pnpm-workspace.yamlSame workspace as 1 Component, 2 entries in managers[]
CD4Cargo.toml [workspace] members = ["crate-a"]1 Component (crate-a)
CD5go.work use ./mod-a ./mod-b2 Components
CD6Single TS project with no markers1 Component (root, id = package.json name)
CD7package.json#name = "@scope/billing"Component.id = "scope-billing", Component.name = "@scope/billing"
CD82 workspaces generate the same id (both "shared")Suffixes appended ("shared-apps" / "shared-packages"). Adding a third workspace elsewhere moves them only if it contends for one of those ids; where the path separates nothing, each id ends in a digest of its own roots[0] and adding a fourth leaves the first three byte-identical
CD9dependencies: {"@nestjs/core": "..."}frameworks = ["nestjs"]
CD10packages/a/package.json#exports: {".": "./src/index.ts"}, or the same at the workspace rootpublicApi = ["packages/a/src/index.ts"], or ["src/index.ts"]
CD11Autodetect finds nothing and there is no package.jsonid = directory name (kebab-case), name = directory name
CD12config.components overrides after autodetectconfig wins (config.md §6.1)
CD13Both pnpm and nx detect the same workspaceDeduped into 1 Component
CD14packages: [".", "packages/*"] on a tree that also holds src/ and a/b/c/d/2 Components: the workspace root (roots: ["."]) and the package
CD15packages: ["packages/*"] where packages/dist/ holds no manifestpackages/dist is not a Component
CD16packages: ["packages/*"] where no matched directory holds a manifestmanagers[] records pnpm with roots: [], §5's fallback makes the whole repository one Component, and both facts are named on stderr
CD17pnpm and nx both claim apps/billing; package.json#name = "@acme/billing-api", project.json#name = "billing-e2e"1 Component, id acme-billing-api, name @acme/billing-api, with the package.json's frameworks and publicApi
CD18nx alone claims apps/billing, project.json#name = "billing-web" and a dependencies key in itid and name billing-web, no frameworks, no publicApi
CD19nx alone claims apps/billing, and a package.json sits beside the project.jsonIdentity, frameworks and publicApi come from the package.json
CD20apps/billing/package.json is not valid JSONDetection aborts with workspace-manifest-malformed naming the file
CD20aOne byte order mark (U+FEFF) opening a candidate's package.json or project.json, the root package.json (with or without workspaces), pnpm-workspace.yaml, or the package.json, Cargo.toml or pyproject.toml §2.1's walk takes for a markerDetected as without it: the same workspace root, Components and ids. Two of them, or one after the first character, in a package.json aborts as CD20 does, and two opening it are named as more than one byte order mark
CD21pnpm-workspace.yaml with no packages: key, or with packages: []Nothing is reported — pnpm includes only the root package either way
CD22turbo.json alone, or nx.json with no project.jsonNothing is reported — neither declares package patterns
CD23packages: whose entry carries a trailing colon, or a workspaces entry that is not a stringDetection aborts with workspace-manifest-malformed naming the manifest and the entry
CD24Components at . and packages/api; a Symbol in packages/api/src/orders.tsSymbol.component is api — the longest root wins, not the first that matches
CD25A Component at packages/api; a Symbol in packages/api-legacy/src/orders.tsSymbol.component is null — roots match whole path segments, not string prefixes
CD26A Component at packages/api; a Symbol in scripts/release.tsSymbol.component is null
CD27Components web and api both declaring roots: ["packages/shared"]Every Symbol under it is api, whichever order the two were declared in
CD28A Symbol the Category B / C rules dropped, in packages/apiSymbol.component is api, as it is for a kept Symbol in the same file
CD29A Component at apps/web; a Symbol whose file is spelled ./apps/web/x.tsSymbol.component is web — the file side is normalized as the root side is
CD30A Component rooted at packages//api; a Symbol in packages/api/x.tsSymbol.component is api — an empty segment names nothing on either side
CD31A Component rooted at "", at "/", or at ../vendorIt claims no file at all, the workspace root included
CD32cwd inside a repository that sits under another marker — a linked worktree at .worktrees/feat in the main checkout, a repository nested in another, a submoduleThe workspace root is that checkout's own top level, the directory holding its .git (a directory or a gitdir: file), not the outer one
CD33cwd inside a monorepo subdirectory holding a .git file that does not open with gitdir: (an empty one left behind)The walk passes it: the workspace root is the monorepo's
CD34A component holding twelve .ts files and a link to a directory outside the workspace that holds twelve .py fileslanguages is ["ts"] — the census does not walk through the link
CD35nx.json, apps/billing/project.json, and apps/alias a link to apps/billingOne Component, rooted at apps/billing
CD36packages: ["packages/*"], packages/billing/package.json, and packages/alias a link to packages/billingTwo Components, rooted at packages/alias and packages/billing; no scanned file belongs to the one at packages/alias
CD37packages: ["*"] and nx.json, with a package.json and a project.json in each of ok/ and a:pkg/ (or x\pkg/)Detection completes: pnpm's and nx's roots are each ["ok"], and no Component is rooted at the odd directory. Both tools report it as left out, each with its own manifest (pnpm-workspace.yaml, nx.json), the reason and the segment to rename
CD38packages: ["*"] whose only match is a:pkg/package.jsonmanagers[] records pnpm with roots: [], a:pkg is reported as left out, the pattern is not reported as one that named no package, and §5's fallback makes the whole repository one Component. ab:pkg/ in its place is a root
CD39packages: ["*/*"] matching d:data/pkg/package.json, or ["*"] matching a directory whose name opens with U+212A KELVIN SIGN and :Each is reported as left out with its directory as spelled on disk, not as NFC spells it; the segment to rename is d:data for the first and the directory itself for the second
CD40repo/pnpm-workspace.yaml declaring ../outside/*, with outside/x\pkg/package.jsonDetection aborts with workspace-root-outside, as for any package under ..: the backslash does not make it a name the workspace holds
CD41src/locked or .config/locked cannot be listed and holds what one search looks for: .py files for the language census, a project.json beside nx.json, or a package.json that packages: ["src/**"] (or [".config/**"]) declaresDetection ends with scan-directory-unreadable naming the directory, and aburi init exits 1
CD42The same, at data/pg, with .gitignore holding pg/The census and the nx search pass over data/pg, and with respectGitignore off end as in CD41. The resolution of packages: ["data/*"] ends as in CD41 either way
CD42anx.json, libs/shared/project.json and build/project.json, with .gitignore holding build/nx's roots are ["libs/shared"]; with respectGitignore off, ["build", "libs/shared"]
CD42bpackages: ["packages/*"], with packages/foo a link to vendor/foo whose resolution fails with EACCES, EPERM or EIODetection ends with scan-directory-unreadable naming packages/foo. With ENOENT or ELOOP it runs, without packages/foo
CD43Twelve .ts files in src and twelve .py files in .config, in .git, in .yarn, or in a linked worktree at .claude/worktrees/featlanguages is ["py", "ts"] for .config, and ["ts"] for the other three
CD44nx.json beside libs/shared/project.json, .github/actions/deploy/project.json, .git/modules/vendored/project.json and, in a linked worktree at .worktrees/feat, libs/shared/project.jsonTwo candidates, .github/actions/deploy and libs/shared
CD44anx.json and libs/shared/project.json, with a project.json under .nx/cache, .nx/workspace-data and .yarn/cache, and respectGitignore offnx's roots are ["libs/shared"], as nx's own file walk passes over those three
CD45packages: ["packages/*", ".github/actions/*"] with a package.json in packages/app, packages/.template and .github/actions/deployTwo candidates, .github/actions/deploy and packages/app
CD46.git/ and .github/actions/deploy/.git/ cannot be listed, beside what each of the three searches looks for in .github/actions/deploy, which packages: [".github/actions/**"] reachesDetection runs: no search lists a .git directory
CD47package.json#main: "./", or exports: {".": "./src/ok.js", "./": "./"}No entry for the package directory: no publicApi key, or publicApi = ["src/ok.js"]. The IR satisfies its schema
CD48main, module, types or typings set to ".", "./.", "././", "./lib/", "./lib/.", "/", "/dist/index.mjs", "C:/dist/index.d.ts", "a:index.js", "../shared/index.d.ts" or "./src/../index.js", or to a value that is not a string; or an exports folder mapping "./lib/": "./lib/"No entry for any of them
CD49main: "././dist/index.js", module: "./dist/./index.js" or types: "dist//index.js"publicApi = ["dist/index.js"] for each
CD50pnpm-workspace.yaml: packages: ["apps/*"] and package.json#workspaces: ["libs/*", "apps/*"] beside pnpm-lock.yaml, with apps/billing and libs/sharedOne managers[] entry, {tool: "pnpm", roots: ["apps/billing", "libs/shared"]}, and one candidate per directory
CD51A value of CD47 and one of CD48 in the package.json of two components whose id collision resolution renames (apps/web, libs/web), beside a component whose root sorts first and whose id sorts last (aaa/zed); and a manifest whose ignored values come in another order than exports then main, module, types, typingsEach value is reported with its component's final id, its manifest's path, its place in the manifest (main, exports["."]), the value and its case, ordered by component id and, within one manifest, as the manifest holds them. Every value CD47 and CD48 name is reported with its own place and case, exports["./lib/"] among them
CD52exports: {"./internal/*": null}, or main: 42No entry and nothing reported

11. Design decisions ​

11.1 Why the workspace root is the first .git, or else the outermost marker ​

When markers are found at multiple levels (e.g., a sub-project inside a monorepo also has a package.json), taking the inner one as root would miss the structure of the entire monorepo. Taking the outermost as root avoids unintended subset detection.

The walk stops at the first .git all the same, because a repository is the unit aburi diff checks a revision out of: a root above it is a tree the base side cannot reproduce. Three layouts put one there, and in each the two sides of a ref diff scanned different trees:

  • A linked worktree kept inside the main checkout (.worktrees/feat). The head scan climbed to the main checkout and read its files, so main..feat reported nothing.
  • A repository nested in another, or a submodule. The head side rooted at the outer directory and the base side at the repository, so every Symbol read as moved under the inner directory's name.
  • A TMPDIR inside the repository. The base worktree is created under the head's own tree, and the base scan climbed out of the worktree into it, so both sides scanned the working tree.

A monorepo whose root is the directory holding its .git is unaffected; a submodule or a vendored repository inside one now roots at itself.

The file walks keep the same boundary from the other side: discovery, the language census and the nx search list nothing in a directory below the workspace root that holds a .git (drop-list.md §10.8). So the checkout around each of these layouts does not read it either: the main checkout's scan leaves a worktree at .worktrees/feat out, and the head scan leaves out the base worktree under an in-repository TMPDIR.

The stop is a .git on disk, and git is asked only while GIT_DIR or GIT_WORK_TREE is set (§2.1). Asking always would cost a git process for every command, a scan outside any repository included, and without those variables git finds the repository through a .git on disk too. A working tree whose repository is kept elsewhere, such as GIT_DIR=~/.dotfiles.git GIT_WORK_TREE=~ or a GIT_DIR whose config sets core.worktree, is the fourth layout. Walking for markers alone, the head scan climbed past it to any marker above, while the base worktree, which git worktree add gives a .git file, rooted at itself, and every Symbol read as moved under the work tree's name. The variables alone do not settle the top, because core.worktree and core.bare live in the repository's config, so git is asked rather than the variables read.

The stop bounds the root walk only. Config discovery still climbs to the filesystem root (cli-spec.md §13), so a worktree under .worktrees/feat roots at itself while still reading the main checkout's aburi.json, whose ignore, components[].roots and relative plugin refs then resolve against the worktree.

11.2 Why framework plugins are not auto-enabled ​

Same reasoning as config.md §15.1: rogue dependencies, unpredictable behavior, hard to trace. Detected framework names are only recorded on the Component; plugin enablement is a user decision (aburi init merely suggests candidates on the console).

11.3 Why package.json name takes top priority for id inference ​

The package.json name in a monorepo is an identifier deliberately chosen by a human. Directory names change easily (e.g., renaming apps → workspaces during refactoring). Prioritizing the package.json name makes Component ids resilient to path changes.

11.4 Why a single project always yields exactly 1 Component ​

Allowing a "zero Components" state breaks the structure of the whole IR (Symbols would have component: null). Guaranteeing at least one Component simplifies Markdown projection / diff.

11.5 Why per-language detectors are deferred ​

Only TS is supported today. Building multi-language detectors when no plugin other than lang-typescript exists would leave them unused. Providing the corresponding detector at the same time each language plugin is added keeps responsibilities clear.

11.6 Limits of publicApi auto-inference ​

The public API expressed by package.json#exports is file-granular; it cannot express fine-grained symbol-level selection (Aburi's publicApi[] accepts globs or symbol ids). Autodetect currently stops at file glob output; if symbol-level filtering is needed, users specify it manually in the config.

In the future, cross-referencing each language plugin's extractSymbols results with package.json#exports leaves room to extend to symbol-level output such as publicApi: ["ts:src/index.ts#Invoice", "ts:src/index.ts#createInvoice"].

12. Attributing Symbols to Components ​

Detection writes components[]; this is how the scan reads it back to fill symbols[].component (ir-schema.md §5).

The rule is over paths and nothing else:

  • A Component claims a file when one of its roots[] is the file itself or a whole-segment prefix of it. packages/api claims packages/api/src/orders.ts and does not claim packages/api-legacy/src/orders.ts
  • When several roots claim the same file, the longest one wins. Nesting is ordinary rather than exceptional: a workspace root that is a package of its own has roots: ["."] containing every other component's root (§3.1.1), so "the first root that matches" would give the whole monorepo to it
  • A file under no root at all is attributed null — the Class A value ir-schema.md §1.1 defines as "outside every Component". §5 guarantees at least one Component, not that its roots cover every file: scripts/ beside packages/* is the ordinary shape that lands here
  • Two Components may name the same root — nothing forbids it, and a config declaring one Component per framework over a shared directory produces it. The lower Component.id takes the files. Lowest rather than first, because id is unique (ir-schema.md §14 #2) and already orders components[], whereas "first" would make attribution depend on the order a config happened to list its components in
  • Both sides of the comparison — the root and the file path — go through one normalization, because they arrive from different places (a config, a filesystem walk) and normalizing one alone turns a match into a miss:
    • NFC, the form every Document string is in (ir-schema.md §1.2, enforced by §14 #19)
    • Path shape per ir-schema.md §14 #10: no leading ./, and the bare . for the workspace root
    • A trailing /, and any empty segment (packages//api), dropped. Neither is something #10 refuses — it admits both — so this is the attribution index's own repair, and it exists because a component rooted at a path holding one would otherwise hold no Symbols at all and say nothing about why
  • A root that names nothing — "" or "/" — claims no files rather than the workspace root, and a root or a file holding .. names something outside the workspace and is refused. Failing closed costs a component its Symbols, which its 0 in the workspace table reports; failing open would hand it every file in the workspace and report nothing
  • A dropped Symbol is attributed exactly like a kept one. The drop is a statement about the Symbol's shape, and the per-component page lists both

What it deliberately does not do: read publicApi[], the import graph, or the manifest. Attribution answers "which package is this file in", which is what Component.roots[] already says; a Symbol re-exported by another component's barrel stays with the file that declares it.

The scan asks the question once per file rather than once per Symbol, since every Symbol from one file shares its answer. The value reaches an effect plugin as owner.component on ClassifyContext, and the call resolver's component-scope tier (§4.5 of call-resolution.md) keys on it — so attribution narrows call resolution as well as filling the per-component views. Two consequences follow from that tier, in opposite directions:

  • A qualified name that exists in two packages at once now resolves, inside the caller's own component, where the two candidates used to make both tiers ambiguous and the call resolved to nothing
  • A qualified call crossing a package boundary now falls through §4.5 to §4.6, so its edge carries low rather than medium. The tier is internal (CallEdge.confidence is not serialized), and the honest claim of the two: nothing about two packages says they are one scope

Released under the Apache License 2.0.