feat(architecture): language/structure-agnostic, configurable seed scanner (#279) (#282)

The `architecture generate` seed was tuned to Go/Rust/JS: a 17-extension
allowlist (Ruby/Elixir/Scala/… → empty map) and a fixed container-dir set
(Java/Maven `src/main/java/…` collapsed the whole project into one `main` box).

Move the source-file scan + component-dir shaping into one
`straymark-core::architecture::scan` module driven by a `ScanConfig`, resolved
from an optional `architecture:` section in `.straymark/config.yml` (additive
over built-in defaults):

- source_extensions — recognize ~30 languages by default (Ruby, Elixir, Scala,
  Dart, Clojure, Vue, Svelte, Lua, Julia, Haskell, Erlang, OCaml, …); extend per
  project.
- scaffolding_prefixes — skip build scaffolding (src/main/java, src/main/kotlin,
  …) so a Maven/Gradle module is attributed to its MODULE dir, not collapsed to
  `main` (multi-module → one box per module). Verified: billing/src/main/java/…
  → `billing`.
- container_dirs / excluded_dirs — extend the descent/skip sets per project.

Defaults unchanged for Go/Rust/JS (Sentinel still seeds 14 components). The
status overlay was already language-agnostic; this only shapes the seed, which
the human/agent then refines. core → 0.7.0 (additive public `scan` API),
documented in CLI-REFERENCE (EN/es/zh-CN).

Closes #279.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: montfort

CHANGELOG.md

@@ -7,6 +7,28 @@ and this project uses [independent versioning](README.md#versioning) for Framewo
 
 ---
 
+## [Unreleased]
+
+### Changed (architecture scanner — language/structure-agnostic, #279, EXPERIMENTAL)
+
+- **`architecture generate` is now configurable and ecosystem-aware.** The source-file scan and
+  the component-dir shaping moved to a single `straymark-core::architecture::scan` module driven
+  by a `ScanConfig`, resolved from an optional **`architecture:` section in
+  `.straymark/config.yml`** (additive over built-in defaults):
+  - `source_extensions` — the seed now recognizes ~30 languages out of the box (added Ruby,
+    Elixir, Scala, Dart, Clojure, Vue, Svelte, Lua, Julia, Haskell, Erlang, OCaml, …); a project
+    in a non-default language is no longer an empty map, and adopters can add more.
+  - `scaffolding_prefixes` — build scaffolding like `src/main/java` / `src/main/kotlin` is skipped,
+    so a **Maven/Gradle** module is attributed to its module directory instead of collapsing the
+    whole project into a single `main` box (multi-module → one component per module).
+  - `container_dirs` / `excluded_dirs` — extend the descent/skip sets per project.
+- Defaults are unchanged for existing Go/Rust/JS layouts (Sentinel still seeds the same 14
+  components); the status overlay was already language-agnostic — this only shapes the seed.
+- `straymark-core` → **0.7.0** (additive: new public `scan` API). Publishes with the next `cli-`
+  release.
+
+---
+
 ## Framework 4.27.0 / CLI 3.26.0 / Core 0.6.0 — 2026-06-16
 
 Audit-prompt hardening (#261), architecture-model DX + a meaningful `has-debt` overlay (#273),

Cargo.lock

@@ -17,7 +17,7 @@ name = "straymark"
 path = "src/main.rs"
 
 [dependencies]
-straymark-core = { version = "0.6.0", path = "../core" }
+straymark-core = { version = "0.7.0", path = "../core" }
 clap = { version = "4", features = ["derive"] }
 reqwest = { version = "0.12", features = ["blocking", "rustls-tls", "json"] }
 serde = { version = "1", features = ["derive"] }

cli/Cargo.toml

@@ -7,18 +7,20 @@
 use std::collections::{BTreeMap, BTreeSet};
 use std::path::{Path, PathBuf};
 
-use straymark_core::architecture::{ArchModel, Component, Layer};
+use straymark_core::architecture::{
+    collect_source_files_with, component_dir_for, resolve_scan_config, ArchModel, Component, Layer,
+};
 use straymark_core::document::{detect_doc_type, discover_documents, DocType};
 use straymark_core::drift::glob_match;
 
 use super::adr_mining;
 use crate::utils;
 
-// The source-file walker (`collect_source_files` + its `EXCLUDED_DIRS`/
-// `SOURCE_EXTENSIONS`) moved to `core::architecture::gather` in Loom A2.0 so the
-// CLI generator and the Loom server share one inventory scan. Re-exported so the
-// `common::collect_source_files` call sites (generate/sync/validate) are
-// unchanged.
+// The source-file walker + the component-dir shaping (extensions, excluded dirs,
+// container descent, build-scaffolding) live in `core::architecture::{gather,
+// scan}` (Loom A2.0; made config-driven in #279) so the CLI generator and the
+// Loom server share one inventory scan. Re-exported so the
+// `common::collect_source_files` call sites (validate/sync) are unchanged.
 pub(crate) use straymark_core::architecture::collect_source_files;
 
 /// The placeholder layer code-derived components land in until the human
@@ -65,49 +67,23 @@ pub(crate) fn artifact_paths(root: &Path, out: Option<&str>) -> (PathBuf, PathBu
     (out_dir, model, drawio)
 }
 
-/// Organizational directories that hold *other* components rather than being
-/// one themselves — the seed descends through them one level so an `internal/`
-/// or `src/` tree breaks out into real components instead of one giant blob
-/// (#273). A leaf like `cmd/` or `db/` is not a container and stays whole.
-pub(crate) const CONTAINER_DIRS: &[&str] =
-    &["internal", "src", "pkg", "lib", "libs", "app", "apps", "modules", "packages"];
-
-/// Distinct component directories under `root` that contain ≥1 source file. A
-/// component dir is the path up to and including the first **non-container**
-/// segment, so `internal/modules/agents/x.go` → `internal/modules/agents`,
-/// `internal/core/bus.go` → `internal/core`, and `cmd/main.go` → `cmd`.
+/// Distinct component directories under `root` that contain ≥1 source file,
+/// shaped by the project's [`ScanConfig`] (#273, #279): the seed descends
+/// through *container* dirs and skips build *scaffolding* (e.g. Maven
+/// `src/main/java`), so `internal/modules/agents/x.go` → `internal/modules/agents`,
+/// `cmd/main.go` → `cmd`, and `billing/src/main/java/…` → `billing`. The config
+/// is resolved once and reused for the file walk.
 pub(crate) fn source_component_dirs(root: &Path) -> Vec<String> {
+    let cfg = resolve_scan_config(root);
     let mut dirs: BTreeSet<String> = BTreeSet::new();
-    for rel in collect_source_files(root) {
-        if let Some(dir) = component_dir_for(&rel) {
+    for rel in collect_source_files_with(root, &cfg) {
+        if let Some(dir) = component_dir_for(&rel, &cfg) {
             dirs.insert(dir);
         }
     }
     dirs.into_iter().collect()
 }
 
-/// The component directory a source file belongs to: descend through container
-/// segments, stop at (and include) the first non-container one. Returns `None`
-/// for a root-level file (no directory to attribute it to).
-fn component_dir_for(rel: &Path) -> Option<String> {
-    let segs: Vec<String> = rel
-        .parent()?
-        .components()
-        .map(|c| c.as_os_str().to_string_lossy().to_string())
-        .collect();
-    if segs.is_empty() {
-        return None;
-    }
-    let mut taken: Vec<&str> = Vec::new();
-    for seg in &segs {
-        taken.push(seg);
-        if !CONTAINER_DIRS.contains(&seg.as_str()) {
-            break;
-        }
-    }
-    Some(taken.join("/"))
-}
-
 /// A component proposed from a source dir (`dir/**`, `unassigned`). The id is
 /// the kebab of the full path (`internal/core` → `internal-core`, unique across
 /// containers); the label is the title-cased leaf segment.
@@ -456,22 +432,8 @@ mod tests {
         assert_eq!(c.globs, vec!["internal/modules/agents/**"]);
     }
 
-    #[test]
-    fn component_dir_descends_through_container_dirs() {
-        // #273: a container tree breaks out; a leaf dir stays whole.
-        let cases = [
-            ("internal/modules/agents/runner.go", Some("internal/modules/agents")),
-            ("internal/core/eventbus/bus.go", Some("internal/core")),
-            ("cmd/server/main.go", Some("cmd")),
-            ("db/seeds/seeds.go", Some("db")),
-            ("src/index.ts", Some("src")), // files directly under a container → the container
-            ("main.go", None),             // root-level file: no dir to attribute
-        ];
-        for (path, want) in cases {
-            let got = component_dir_for(Path::new(path));
-            assert_eq!(got.as_deref(), want, "for {path}");
-        }
-    }
+    // (component-dir descent + Maven scaffolding are tested in
+    // `core::architecture::scan` — the logic moved there in #279.)
 
     #[test]
     fn generated_model_passes_core_validation() {

cli/src/commands/architecture/common.rs

@@ -1,6 +1,6 @@
 [package]
 name = "straymark-core"
-version = "0.6.0"
+version = "0.7.0"
 edition = "2021"
 description = "Shared document model and knowledge graph for StrayMark — parses governance documents and builds their typed traceability graph"
 license = "MIT"

core/Cargo.toml

@@ -19,21 +19,10 @@ use crate::ailog;
 use crate::architecture::projection::GovernanceState;
 use crate::charter::{self, Charter, CharterStatus};
 use crate::charter_files::parse_files_to_modify;
+use crate::architecture::scan::{resolve_scan_config, ScanConfig};
 use crate::document::{detect_doc_type, discover_documents, parse_document, DocType};
 use crate::drift::compute_drift;
 
-/// Directories never scanned for source (build output, VCS, deps, docs).
-pub const EXCLUDED_DIRS: &[&str] = &[
-    ".straymark", ".git", "node_modules", "target", "vendor", "dist", "build",
-    ".venv", "__pycache__", ".github", "docs",
-];
-
-/// Extensions that mark a file as source worth counting in the inventory.
-pub const SOURCE_EXTENSIONS: &[&str] = &[
-    "rs", "py", "js", "ts", "jsx", "tsx", "java", "go", "cs", "cpp", "cc",
-    "cxx", "c", "h", "php", "kt", "swift",
-];
-
 /// Gather the governance-derived file sets (Spec 002 §4) the pure projection
 /// consumes. All impure work (git, fs walk, document parsing) lives here; the
 /// projection itself ([`super::projection::project`]) stays pure.
@@ -84,27 +73,34 @@ pub fn build_governance_state(root: &Path) -> GovernanceState {
     }
 }
 
-/// Source files (paths relative to `root`), skipping [`EXCLUDED_DIRS`]. Used for
-/// the on-disk inventory (the `uncharted` signal) and by the CLI generator to
-/// discover top-level component directories.
+/// Source files (paths relative to `root`), filtered by the project's
+/// [`ScanConfig`] (source extensions + excluded dirs, defaults ∪ the
+/// `architecture:` config section, #279). Used for the on-disk inventory (the
+/// `uncharted` signal) and by the CLI generator to discover component dirs.
 pub fn collect_source_files(root: &Path) -> Vec<PathBuf> {
-    fn walk(dir: &Path, root: &Path, out: &mut Vec<PathBuf>) {
+    collect_source_files_with(root, &resolve_scan_config(root))
+}
+
+/// [`collect_source_files`] with an explicit config (so a caller that already
+/// resolved one — e.g. the generator computing component dirs — reuses it).
+pub fn collect_source_files_with(root: &Path, cfg: &ScanConfig) -> Vec<PathBuf> {
+    fn walk(dir: &Path, root: &Path, cfg: &ScanConfig, out: &mut Vec<PathBuf>) {
         let Ok(entries) = std::fs::read_dir(dir) else {
             return;
         };
         for entry in entries.flatten() {
             let path = entry.path();
             if path.is_dir() {
                 if let Some(name) = path.file_name().and_then(|n| n.to_str()) {
-                    if !EXCLUDED_DIRS.contains(&name) {
-                        walk(&path, root, out);
+                    if !cfg.is_excluded_dir(name) {
+                        walk(&path, root, cfg, out);
                     }
                 }
             } else if path.is_file() {
                 let is_source = path
                     .extension()
                     .and_then(|e| e.to_str())
-                    .is_some_and(|ext| SOURCE_EXTENSIONS.contains(&ext));
+                    .is_some_and(|ext| cfg.is_source_ext(ext));
                 if is_source {
                     if let Ok(rel) = path.strip_prefix(root) {
                         out.push(rel.to_path_buf());
@@ -114,7 +110,7 @@ pub fn collect_source_files(root: &Path) -> Vec<PathBuf> {
         }
     }
     let mut out = Vec::new();
-    walk(root, root, &mut out);
+    walk(root, root, cfg, &mut out);
     out
 }
 

core/src/architecture/gather.rs

@@ -12,8 +12,10 @@
 pub mod gather;
 pub mod model;
 pub mod projection;
+pub mod scan;
 
-pub use gather::{build_governance_state, collect_source_files};
+pub use gather::{build_governance_state, collect_source_files, collect_source_files_with};
+pub use scan::{component_dir_for, resolve_scan_config, ScanConfig};
 pub use model::{parse_model, parse_model_str, validate_structure, ArchModel, Component, Layer, ModelIssue};
 pub use projection::{
     project, validate_model, ComponentProjection, ComponentState, GovernanceState,