Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 24 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -332,6 +332,26 @@ sources are additive: the file cannot re-include a built-in cache/vendor/output
excluded explicitly through `CheckOptions`. The cache identity includes the normalized root-file
path, its presence, and a SHA-256 fingerprint of its exact bytes, so edits invalidate cached graphs.

### Zig workspaces and nested packages

`ExtractionOptions.workspace.mode` selects one of three scopes: the located package (the compatible
default), an explicit borrowed list of `WorkspacePackage` values, or every `build.zig.zon` package
discovered below the located repository root. Explicit packages provide an `id` and root-relative
`path`. Discovered ids are their normalized manifest-directory paths, with `.` naming a root
package. Cache, VCS, output, documentation, dependency, symlink, and reparse-point trees are never
entered during discovery.

Workspace graph identifiers are `package_id::package-relative/path`, so `api::src/main.zig` and
`worker::src/main.zig` cannot collapse. The single-package mode retains ordinary `src/main.zig`
identifiers. Workspace `CompilationUnitOverride` values set `package_id`; a project-origin module
mapping without its own `package_id` resolves inside that unit's package, while an explicit target
package models a local cross-package alias. `root` always resolves in the selected unit's package.

The workspace-root `.archignore` matches physical repository-relative paths, each selected package's
own `.archignore` matches package-relative paths, and `ExtractionOptions.exclusions` matches qualified
workspace identifiers. All are additive. Workspace cache keys include the selected mode/list and the
resolved package identities, canonical paths, manifest fingerprints, and ignore fingerprints.

## Limitations

| Area | Current contract |
Expand All @@ -350,9 +370,10 @@ path, its presence, and a SHA-256 fingerprint of its exact bytes, so edits inval
## Configuration and diagnostics

`CheckOptions` carries the allocator, `std.Io`, working directory, empty-test policy, cache control,
logging, and one `ExtractionOptions` value. Extraction options cover exclusions, strictness,
resource/C-header inclusion, test-import inclusion, compilation-unit mappings, and the currently
explicit-only build-graph mode. Every field that changes a graph participates in its cache key.
logging, and one `ExtractionOptions` value. Extraction options cover exclusions, workspace scope,
strictness, resource/C-header inclusion, test-import inclusion, compilation-unit mappings, and the
currently explicit-only build-graph mode. Every field that changes a graph participates in its
cache key.

Logging is disabled by default. A check can borrow an ordinary writer, structured `LogSink`, and/or
file sink with explicit output directory and prefix. Levels are `debug`, `info`, `warn`, and
Expand Down
6 changes: 5 additions & 1 deletion docs-site/pages/extraction-modules.html
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@ <h2 id="archignore">Project-wide source exclusions</h2>
<p>An optional <code>.archignore</code> beside the located root marker applies to direct enumeration and every fluent architecture check. It uses ArchUnitZig globs: <code>*</code> stays in one segment, <code>**</code> crosses segments, a leading <code>/</code> anchors at the root, separator-free patterns match basenames at any depth, and Windows separators are accepted. Blank lines and full-line <code>#</code> comments are ignored.</p>
<p>Only the root file is authoritative. Nested files do not override it, and its patterns are additive with explicit and built-in exclusions. Gitignore negation is intentionally unsupported; a line beginning with <code>!</code> is an <code>InvalidPattern</code> error rather than an inert policy.</p>

<h2 id="workspaces">Workspaces and nested packages</h2>
<p>The compatible default analyzes only the located package. Workspace mode can instead select an explicit list of package ids and root-relative paths, or discover every <code>build.zig.zon</code> below a repository root. Discovery prunes dependency, vendor, cache, VCS, output, documentation, symlink, and reparse-point trees.</p>
<p>Workspace identifiers are <code>package_id::package-relative/path</code>. Discovered ids are manifest-directory paths (<code>.</code> for the root); explicit ids are caller supplied. Compilation units name their package, <code>root</code> stays in that package, and project-origin aliases may deliberately target another selected package. The workspace root ignore file matches physical repository paths, package ignore files match package-relative paths, and explicit exclusions match qualified identifiers.</p>

<h2 id="syntax">Dependency syntax</h2>
<p>The extractor recognizes literal <code>@import</code>, <code>@embedFile</code>, and deprecated <code>@cImport</code>/<code>@cInclude</code> forms without evaluating code. Comments, ordinary string contents, and multiline strings cannot become false dependencies.</p>
<div class="cards">
Expand Down Expand Up @@ -38,7 +42,7 @@ <h2 id="test-imports">Production graphs and colocated tests</h2>
<p>Zig test declarations live beside production code, so their imports are visible by default. Set <code>ExtractionOptions.include_test_imports = false</code> when enforcing a production-only architecture. Ordinary <code>comptime</code> dependencies remain included.</p>

<h2 id="cache">Deterministic cache identity</h2>
<p>Graph-cache keys encode the canonical project root and every extraction option, including ordered compilation-unit mappings and test-import behavior. They also encode the normalized root <code>.archignore</code> path, presence, and exact-content SHA-256 fingerprint, so edits invalidate prior results. Caller-owned caches are unsynchronized; the optional process cache is mutex-protected. Reads return clones, so clearing a cache cannot invalidate a graph already returned to a caller.</p>
<p>Graph-cache keys encode the canonical project root and every extraction option, including workspace selection, ordered compilation-unit mappings, and test-import behavior. They also encode root/package ignore fingerprints plus every selected manifest's canonical path and exact-content fingerprint, so edits or newly discovered packages invalidate prior results. Caller-owned caches are unsynchronized; the optional process cache is mutex-protected. Reads return clones, so clearing a cache cannot invalidate a graph already returned to a caller.</p>

<h2 id="ignores">Local dependency suppressions</h2>
<p><code>// archunit: ignore</code> may suppress one intentional dependency occurrence. A trailing directive applies to calls on that line; a standalone directive applies only to the builtin on the next physical line. Optional target names are exact after Zig string decoding. Malformed directives are reported instead of silently changing the graph.</p>
Expand Down
2 changes: 1 addition & 1 deletion docs-site/pages/limitations.html
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ <h1>Current limitations and honest boundaries</h1>
<p class="lead">ArchUnitZig prefers explicit missing behavior over apparent parity built on Zig concepts that do not exist or cannot be discovered reliably without running user code.</p>

<h2 id="build-graph">No automatic <code>build.zig</code> interpretation</h2>
<p>Named module imports need a compilation-unit alias table. Zig build files are programs: their module graph can depend on target, options, environment, filesystem state, and control flow. ArchUnitZig does not run them or recognize a misleading subset. Provide <code>CompilationUnitOverride</code> values explicitly.</p>
<p>Named module imports need a compilation-unit alias table. Zig build files are programs: their module graph can depend on target, options, environment, filesystem state, and control flow. ArchUnitZig does not run them or recognize a misleading subset. Workspace discovery finds package boundaries from manifests; it does not infer compilation roots or aliases. Provide <code>CompilationUnitOverride</code> values explicitly.</p>

<h2 id="dynamic-imports">Literal dependency calls only</h2>
<p>The extractor records literal <code>@import</code>, <code>@embedFile</code>, and supported C-import forms. A computed dependency operand is a parser-policy error in strict mode because static analysis cannot name its target without execution.</p>
Expand Down
20 changes: 13 additions & 7 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -208,13 +208,19 @@ blank lines and full-line `#` comments are metadata; negation is deliberately un
nested `.archignore` files do not alter the root policy.

Extraction settings live in one `ExtractionOptions` value: exclusions, parser strictness,
resource/C-header toggles, explicit compilation-unit mappings, and build-graph mode. Graph-cache
keys use the canonical project root plus a length-delimited encoding of every field. They also encode
the normalized root `.archignore` path, whether the file exists, and the SHA-256 fingerprint of its
exact bytes. A schema test reflects over the options and nested module-mapping structs, so adding a
field without acknowledging it in key construction fails the suite. Slice order is significant;
this may conservatively miss an equivalent hit but cannot return a graph produced for different
input.
resource/C-header toggles, workspace scope, explicit compilation-unit mappings, and build-graph
mode. Single-package scope retains package-relative identifiers. Explicit and discovered workspace
scopes qualify every internal identifier as `package_id::package-relative/path`; discovered package
ids are normalized manifest-directory paths and explicit ids are caller-owned labels. Nested
manifests are package boundaries even while discovery continues below them to find deeper packages.

Graph-cache keys use the canonical project root plus a length-delimited encoding of every field.
They also encode the normalized root `.archignore` path, whether the file exists, and the SHA-256
fingerprint of its exact bytes. Workspace keys additionally encode every resolved package's identity,
canonical/relative paths, exact manifest fingerprint, and package-ignore fingerprint. A schema test
reflects over options, workspace selections, and nested module-mapping structs, so adding a field
without acknowledging it in key construction fails the suite. Slice order is significant; this may
conservatively miss an equivalent hit but cannot return a graph produced for different input.

`GraphCache` instances own cloned keys and graphs and are deliberately not synchronized. Reads also
return clones, so clearing or destroying a cache never invalidates a caller's graph. The process-wide
Expand Down
41 changes: 41 additions & 0 deletions docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -1283,3 +1283,44 @@ Consequence: repositories can keep generated or vendored source out of every arc
without repeating options in each test; configuration errors are visible; Windows-authored patterns
stay portable; nested projects cannot silently override their parent's scan; and cached graphs never
outlive the exact root policy bytes that selected their source files.

### D052 — Workspace identity is explicit and build scripts remain inert

`ExtractionOptions.workspace.mode` is `single_package`, `explicit_packages`, or
`discover_packages`. The compatible default preserves every existing package-relative identifier and
stops at nested marked projects. Explicit mode requires a non-empty borrowed list of unique
`WorkspacePackage { id, path }` values whose canonical directories remain below the located root and
contain `build.zig.zon`. Discovery mode accepts no explicit list and finds the root manifest plus all
nested manifests beneath the located repository root. It prunes the same cache, VCS, output,
documentation, dependency, symlink, and reparse-point boundaries as source enumeration, but it keeps
searching below one package to find deliberately nested packages.

Workspace internal identifiers are `package_id::package-relative/path`. Explicit ids are validated
non-empty labels without `::`; discovered ids are normalized manifest-directory paths and `.` names
the root. This namespace is visible to selectors and reports, rather than hiding identity in cache-
only metadata. Two packages may therefore own identical `src/main.zig` paths without creating one
node or merging edges. Single-package consumers pay no migration cost.

Workspace compilation units require `CompilationUnitOverride.package_id`. Root-source paths remain
package-relative, and `@import("root")` resolves only inside that unit's package. A project-origin
`ModuleOverride` without `package_id` targets the unit package; setting it names another selected
package and models a local cross-package alias. Package-origin aliases remain external and cannot
also name a workspace package. No `build.zig` code is executed and no alias table is guessed from
manifest dependency declarations.

Exclusions have three deliberate coordinate systems. The workspace-root `.archignore` is matched
against physical repository-relative paths during discovery and corpus assembly. Each package-root
`.archignore` is matched against its package-relative paths by the ordinary enumerator. Explicit
`ExtractionOptions.exclusions` are matched against final qualified identifiers. All remain additive;
built-in directory pruning applies both to discovery and per-package traversal.

One owned workspace snapshot is shared by cache-key construction and extraction. It records sorted
package ids, normalized relative and canonical paths, exact `build.zig.zon` SHA-256 fingerprints,
and each package ignore path/presence/fingerprint. The cache key also encodes the workspace mode and
ordered explicit selection input. Adding, removing, moving, renaming, or editing a selected manifest
or policy therefore separates graphs without a read-key/read-scan race.

Consequence: monorepos can analyze one package, a reviewed set, or all manifest packages; duplicate
relative paths remain distinct; local module edges and `root` keep compilation context; dependency
caches stay outside discovery; and workspace topology changes cannot reuse a stale single-package or
multi-package cache entry.
7 changes: 7 additions & 0 deletions src/common/extraction.zig
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@ pub const extractProjectGraphLogged = @import("extraction/project_graph.zig").ex
pub const GraphCache = @import("extraction/graph_cache.zig").GraphCache;
pub const GraphCacheKey = @import("extraction/graph_cache.zig").GraphCacheKey;
pub const ExtractionOptions = @import("extraction/extraction_options.zig").ExtractionOptions;
pub const WorkspaceMode = @import("extraction/extraction_options.zig").WorkspaceMode;
pub const WorkspaceOptions = @import("extraction/extraction_options.zig").WorkspaceOptions;
pub const WorkspacePackage = @import("extraction/extraction_options.zig").WorkspacePackage;
pub const SourceReferences = @import("extraction/graph_normalizer.zig").SourceReferences;
pub const ImportKind = @import("extraction/import_kind.zig").ImportKind;
pub const ImportKinds = @import("extraction/import_kind.zig").ImportKinds;
Expand All @@ -18,6 +21,7 @@ pub const ModuleOverride = @import("extraction/module_resolver.zig").ModuleOverr
pub const ModuleResolutionOverrides = @import("extraction/module_resolver.zig").ModuleResolutionOverrides;
pub const ModuleResolutionStatus = @import("extraction/module_resolver.zig").ModuleResolutionStatus;
pub const ResolvedModuleReference = @import("extraction/module_resolver.zig").ResolvedModuleReference;
pub const WorkspacePackageRoot = @import("extraction/module_resolver.zig").WorkspacePackageRoot;
pub const ProjectMarker = @import("extraction/project_locator.zig").ProjectMarker;
pub const EnumerationOptions = @import("extraction/source_files.zig").EnumerationOptions;
pub const FileResolutionInput = @import("extraction/classifier.zig").FileResolutionInput;
Expand Down Expand Up @@ -46,6 +50,7 @@ pub const parseSource = @import("extraction/source_parser.zig").parseSource;
pub const normalizeGraph = @import("extraction/graph_normalizer.zig").normalizeGraph;
pub const resolveRelativeReference = @import("extraction/relative_resolver.zig").resolveRelativeReference;
pub const resolveModuleReference = @import("extraction/module_resolver.zig").resolveModuleReference;
pub const resolveWorkspaceModuleReference = @import("extraction/module_resolver.zig").resolveWorkspaceModuleReference;
pub const storeGraphInCache = @import("extraction/graph_cache.zig").storeGraphInCache;
pub const validateModuleResolutionOverrides = @import("extraction/module_resolver.zig").validateModuleResolutionOverrides;
pub const locateProject = @import("extraction/project_locator.zig").locateProject;
Expand All @@ -69,4 +74,6 @@ test {
_ = @import("extraction/source_files.zig");
_ = @import("extraction/source_parser.zig");
_ = @import("extraction/source_location.zig");
_ = @import("extraction/workspace.zig");
_ = @import("extraction/workspace_options.zig");
}
7 changes: 7 additions & 0 deletions src/common/extraction/extraction_options.zig
Original file line number Diff line number Diff line change
@@ -1,16 +1,23 @@
const module_resolver = @import("module_resolver.zig");
const source_parser = @import("source_parser.zig");
const workspace_options = @import("workspace_options.zig");

pub const BuildGraphMode = enum {
disabled,
explicit_only,
};

pub const WorkspaceMode = workspace_options.WorkspaceMode;
pub const WorkspaceOptions = workspace_options.WorkspaceOptions;
pub const WorkspacePackage = workspace_options.WorkspacePackage;

/// Every option here changes extraction output and therefore belongs in `buildGraphCacheKey`.
/// All slices and nested module mappings are borrowed for the duration of extraction/key creation.
pub const ExtractionOptions = struct {
/// Additional project-relative globs beyond the enumerator defaults.
exclusions: []const []const u8 = &.{},
/// One located package by default, or an explicit/discovered manifest workspace.
workspace: WorkspaceOptions = .{},
/// Whether invalid source aborts extraction or becomes owned diagnostics.
strictness: source_parser.Strictness = .strict,
/// Whether `@embedFile` targets participate in the graph.
Expand Down
Loading