Documentation
¶
Index ¶
Constants ¶
const ConfigFileName = ".mache.json"
ConfigFileName is the convention file looked up by `mache serve`.
const SmellRulesEnvVar = "MACHE_SMELL_RULES_DIR"
SmellRulesEnvVar names the environment variable that points to a directory of JSON files containing additional SmellRule entries. External rules are appended to the built-in registry at process start and are otherwise indistinguishable from built-ins — same MCP shape, same query contract, same pre-flight table check.
Each file in the directory must be a single SmellRule object (not an array — one rule per file keeps diffs clean and avoids "the third rule errored, what was the first?" debugging). The loader is fail-fast: a single read / parse / validation / collision error aborts loading, returning the error to the caller. init() logs and skips all external rules in that case so a typo can't take down the server; tests assert the error directly.
Variables ¶
var ( Version = "dev" Commit = "none" Date = "unknown" )
Functions ¶
func LoadCapnpBindings ¶ added in v0.8.0
LoadCapnpBindings populates the per-connection _capnp_binding_refs TEMP table from the sibling .bindings.capnp event log of dbPath. Must be called AFTER ensureCanonicalViews on the same connection (the TEMP table is created there).
No-op when the sibling log is missing (returns nil) — the canonical view's UNION arm just stays empty. Returns an error when the log exists but is corrupt.
Producers that write to BOTH _lsp_refs AND .bindings.capnp will produce duplicate-shaped rows in v_refs (one per producer); set- membership consumers (alive-check in dead_code) deduplicate naturally, so this isn't a correctness issue. Once the capnp event log is the canonical producer (post-T8.5), the _lsp_refs UNION arm in ensureCanonicalViews can be removed.
func PresetNames ¶ added in v0.6.0
func PresetNames() []string
PresetNames returns the sorted list of available preset schema names.
Types ¶
type MountMetadata ¶ added in v0.2.0
type MountMetadata struct {
PID int `json:"pid"`
Source string `json:"source"`
MountPoint string `json:"mount_point"`
Type string `json:"type,omitempty"` // "nfs", "fuse", "mcp-http", "mcp-stdio"
GitRepo string `json:"git_repo,omitempty"` // org/repo
GitBranch string `json:"git_branch,omitempty"` // branch name
GitRemote string `json:"git_remote,omitempty"` // full remote URL
Timestamp time.Time `json:"timestamp"`
Writable bool `json:"writable"`
Addr string `json:"addr,omitempty"` // listen address for MCP HTTP servers
}
MountMetadata stores information about an agent-mode mount.
type ProjectConfig ¶ added in v0.6.0
type ProjectConfig struct {
Sources []SourceConfig `json:"sources"`
}
ProjectConfig represents the .mache.json project configuration.
type SmellRule ¶ added in v0.8.0
type SmellRule struct {
ID string // stable identifier, used as the MCP tool argument
Languages []string // matches `_source.language` values; empty = any
Description string // shown in the help payload
Query string // SQL with one `%s` placeholder for the optional scope clause
ScopeColumn string // SQL expression to compare to source_id; empty disables source_id scoping
// Requires lists the SQL tables this rule reads. Surfaced in the
// rules listing so an agent can decide upfront whether the rule is
// usable on the active backend. Standalone mache emits `nodes`,
// `node_refs`, `node_defs`; LLO-built .db additionally has `_ast`,
// `_source`, `_imports`, `_lsp*`. See docs/ARCHITECTURE.md
// "Interplay with ley-line-open" for the full table.
Requires []string
// DefaultMinMetric is the rule's recommended metric threshold
// when the request omits min_metric. Zero means "no default
// threshold; return all rows." Used for metric-bearing rules
// where the query's natural output includes a long tail of
// uninteresting low-metric rows (e.g. long_function returns
// every function regardless of size; without a default
// threshold the response is dominated by 1-line setters).
// Callers can pass min_metric=0 explicitly to override the
// default and see everything; any non-zero min_metric also
// overrides.
DefaultMinMetric int64
}
SmellRule describes one structural code-smell pattern. Rules are language-aware: each carries the language(s) it applies to plus a SQL query template that runs against the `_ast` / `nodes` / `node_defs` / `node_refs` tables produced by `leyline parse`.
The query MUST select exactly seven columns:
source_id, node_id, start_byte, end_byte, start_row, start_col, metric
in that order. `metric` is an integer score (cyclomatic complexity, fan-out count, line length, etc.); binary rules that don't carry a metric emit `0 AS metric`. The handler shapes the row into a uniform response with 1-based line/column and an optional snippet.
`ScopeColumn` is the SQL expression the handler will compare to source_id when the caller passes `source_id` to find_smells (e.g. "lit.source_id" for AST-walking rules; "n.source_file" for rules that join via nodes). The query template MUST contain a single `%s` placeholder where the scope clause should be spliced in; rules unconcerned with scoping can leave ScopeColumn blank.
Threshold filtering on the metric column is server-side via the `min_metric` request arg — handler drops findings whose metric is below the cutoff before returning. Default 0 keeps every row.
Bead mache-6z2e tracks the broader "machelint" idea — declarative rules consumed via this tool. Today the registry is hard-coded; in the future it becomes user-extensible (declarative JSON, per-repo overrides, etc.).
func LoadExternalSmellRules ¶ added in v0.8.0
LoadExternalSmellRules reads `*.json` files from dir, parses each as a SmellRule, validates the result, and returns the parsed rules. Fail-fast: any read, parse, validation, or collision error aborts and returns immediately — caller decides whether to log+skip or treat as fatal. init() logs and skips; tests fail loudly.
Validation:
- ID must be non-empty and not collide with a built-in rule (or another external loaded from this same dir)
- Query must be non-empty, contain exactly one '%s' placeholder for the scope clause, AND be a valid fmt.Sprintf format string (no stray `%` chars that fmt would treat as verbs — common trap with SQL `LIKE '%foo%'` patterns; escape as `%%`)
- Requires may be empty (rule reads no tables) or list table names
type SourceConfig ¶ added in v0.6.0
SourceConfig describes a single data source within a project.
Source Files
¶
- agent.go
- build.go
- call_extractor_ast.go
- config.go
- find_smells_cli.go
- infer.go
- init.go
- leyline.go
- mount.go
- schemas.go
- serve.go
- serve_architecture.go
- serve_diagram.go
- serve_find_smells.go
- serve_find_smells_load.go
- serve_handlers.go
- serve_hosted.go
- serve_impact.go
- serve_lsp.go
- serve_mount_annotate.go
- serve_registry.go
- serve_repo.go
- serve_resolve_ref.go
- serve_write.go
- sheaf_push_log.go
- uds_graph.go
- utils.go