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
16 changes: 15 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -318,6 +318,20 @@ module alias table. Multiple roots may map the same alias differently. Unknown a
silently disappear. Strict parsing rejects malformed source and non-literal operands; permissive
parsing returns owned syntax diagnostics and no partial edges from a rejected file.

### Project-level `.archignore`

An optional `.archignore` at the located project root adds exclusions to every architecture scan.
It uses the same case-sensitive ArchUnit glob syntax as `ExtractionOptions.exclusions`: `*` stays
within one path segment, `**` crosses segments, `/pattern` is rooted, a pattern without a separator
matches a basename at any depth, and `\` is accepted as a path separator. Blank lines and full-line
`#` comments are ignored. Inline comments and gitignore negation are not supported; a line beginning
with `!` fails with `InvalidPattern` instead of silently behaving like a different language.

Only the root file is read. Nested `.archignore` files have no effect, and all three exclusion
sources are additive: the file cannot re-include a built-in cache/vendor/output directory or a path
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.

## Limitations

| Area | Current contract |
Expand All @@ -330,7 +344,7 @@ parsing returns owned syntax diagnostics and no partial edges from a rejected fi
| Language model | There are no class/interface rules, LCOM, abstractness, main-sequence distance, or class-oriented zone metrics. |
| Visibility | Zig declaration visibility is not treated as abstractness or an architecture layer. |
| Slice vocabulary | Only the projection, dependency, PlantUML, and export methods documented above are shipped; sibling-only slice methods are not implied. |
| Filesystem traversal | Symlinks/reparse points are not followed, nested marked Zig projects are boundaries, and cache/VCS/output/docs/dependency trees are excluded by default. |
| Filesystem traversal | Symlinks/reparse points are not followed, nested marked Zig projects are boundaries, cache/VCS/output/docs/dependency trees are excluded by default, and only the project-root `.archignore` is loaded. |
| Concurrency | Graph cache instances are unsynchronized; the process-wide cache is mutex-protected, but caller-owned writers and sinks need their own coordination if shared. |

## Configuration and diagnostics
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 @@ -5,6 +5,10 @@ <h2 id="discovery">Project discovery and enumeration</h2>
<p>Pass an explicit project directory or marker, or let discovery walk upward to the nearest <code>build.zig.zon</code> and then <code>build.zig</code>. Enumeration returns sorted lowercase <code>.zig</code> and <code>.zon</code> paths. Cache, VCS, output, dependency, and nested-project directories are excluded by default; custom exclusions are additive.</p>
<p>Symlinks and Windows reparse points are not followed. This keeps traversal bounded and makes an external target's classification independent of filesystem aliases.</p>

<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="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 @@ -34,7 +38,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. 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 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>

<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 @@ -8,7 +8,7 @@ <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>

<h2 id="filesystem">Traversal is deliberately conservative</h2>
<p>Symlinks and Windows reparse points are not followed. Nested marked Zig projects are traversal boundaries by default. Existing relative targets are canonicalized against the project root, and paths leaving that root remain external/outside rather than being silently folded into the project graph.</p>
<p>Symlinks and Windows reparse points are not followed. Nested marked Zig projects are traversal boundaries by default, and nested <code>.archignore</code> files do not alter the located root's policy. Existing relative targets are canonicalized against the project root, and paths leaving that root remain external/outside rather than being silently folded into the project graph.</p>

<h2 id="language-metrics">No class-oriented metrics</h2>
<p>There is no class/interface rule surface, inheritance policy, LCOM, abstractness, distance-from-main-sequence, or zone label. Zig declarations, containers, source structure, imports, graph coupling, and user-defined metrics are the supported vocabulary.</p>
Expand Down
15 changes: 10 additions & 5 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -202,14 +202,19 @@ Project discovery canonicalises an explicit directory/marker or searches upward
excluded directories are never opened recursively. Symlink/reparse entries are not followed, and a
nested marked Zig project is a traversal boundary by default. The owned result contains sorted,
project-relative `/` paths for lowercase `.zig` and `.zon` files; custom exclusion globs are additive
to the documented cache, VCS, output, documentation, and dependency defaults.
to the documented cache, VCS, output, documentation, and dependency defaults. An optional
project-root `.archignore` supplies a second additive list in the same ArchUnit glob grammar. Only
blank lines and full-line `#` comments are metadata; negation is deliberately unsupported, and
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. 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.
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.

`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
35 changes: 35 additions & 0 deletions docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -1248,3 +1248,38 @@ headroom. CI uploads the raw JSON so future optimisation begins from comparable
Consequence: correctness and cache isolation cannot be traded for a faster number; performance
regressions are visible by stage; allocations can be profiled without platform-specific tooling;
and budget changes remain auditable against hosted evidence rather than one workstation.

### D051 — `.archignore` reuses one exclusion language

The optional project-root `.archignore` uses ArchUnitZig's existing glob language. A pattern without
a path separator selects a basename at any depth; a pattern containing `/` or `\` selects a complete
project-relative path; a leading `/` anchors an otherwise basename-shaped pattern at the project
root; and a trailing separator selects a directory for traversal pruning. `*`, `**`, `?`, and
character classes retain the same case-sensitive behavior as programmatic extraction exclusions.
This is deliberately not advertised as gitignore compatibility.

Surrounding spaces, tabs, and carriage returns are trimmed around each physical line. Empty lines
and lines whose first remaining byte is `#` are ignored. `#` elsewhere is literal. Negation is not
supported because re-inclusion would conflict with selective traversal and the promise that built-in
cache, VCS, output, documentation, and dependency boundaries are never entered. A first
non-whitespace `!`, an empty rooted pattern,
`.` or `..` path segments, NUL bytes, and invalid ArchUnit globs are user-facing `InvalidPattern`
errors with a `project.parse_archignore` diagnostic. Failing closed avoids accepting policy text
with semantics borrowed accidentally from another ignore language.

Exactly one file is authoritative: `.archignore` beside the located root marker. Nested files are
ordinary non-analyzable files and have no policy effect. Its patterns, explicit
`ExtractionOptions.exclusions`, and built-in exclusions form an additive union; none can re-include
another source's exclusion. The loaded root policy is owned for one extraction and shared by cache-
key construction and enumeration, avoiding a read-key/read-scan race inside one operation.

The graph-cache key encodes the normalized absolute `.archignore` path, an explicit present/absent
byte, and a SHA-256 fingerprint of the exact file bytes. Thus missing and empty files differ, and
comments or line-ending edits conservatively invalidate the graph even when their effective pattern
set is unchanged. Direct source enumeration loads the same root policy, so the public low-level API
and fluent graph extraction cannot disagree.

Consequence: repositories can keep generated or vendored source out of every architecture corpus
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.
1 change: 1 addition & 0 deletions src/common/extraction.zig
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ pub const locateProject = @import("extraction/project_locator.zig").locateProjec

test {
_ = @import("path.zig");
_ = @import("extraction/archignore.zig");
_ = @import("extraction/classifier.zig");
_ = @import("extraction/edge.zig");
_ = @import("extraction/extraction_options.zig");
Expand Down
Loading