archsutra-ai 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes follow [Semantic Versioning](https://semver.org/).
 
+## 0.1.4 - 2026-11-07
+
+### Added
+- `.archsutra/suppress.json` hides a finding when `rule`, `path`, and `reason` match. A row without a reason is ignored. A row whose `expires` date is past is ignored.
+- Import edges for Go, Java, Kotlin, C#, and Rust by matching an import suffix to a module directory.
+- `drift` and `compare` diff two `findings.json` files, or a project against `--baseline`. `--fail-on` applies to added findings. `compare` does not run Semgrep.
+- `review`, `design`, `threat-model`, `modernize`, and `cost` write an evidence starter. Sections the scanner cannot decide stay `unknown`. Exit code 3 is unused.
+- `archsutra mcp` speaks MCP on stdio. Tools: `archsutra_audit`, `archsutra_map`, `archsutra_drift`.
+
+### Changed
+- Release workflow publishes `npm publish --provenance --access public` after the GitHub release. This needs an npm trusted publisher for `release.yml`. `0.1.3` is not republished.
+
+## Unreleased
+
+### Changed
+- Docs now match the registry and CI. `archsutra-ai` is on npm (`0.1.2`, `0.1.3`). Homepage stats are 31 tests and Ubuntu plus Windows. OpenSSF Scorecard **5.7 / 10** (2026-11-06) is quoted with the failing checks. Install examples pin `archsutra-ai@0.1.3` because the `v0.1.2` tag has no `archsutra-ai` bin.
+- Recorded the release split: no `v0.1.3` git tag, npm `0.1.3` `gitHead` is `4a7ab27`, no npm provenance. Next publish has to be `0.1.4` or later, from Actions.
+
 ## 0.1.3 - 2026-11-06
 
 ### Fixed

package/README.md

@@ -11,7 +11,7 @@
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 ![Node](https://img.shields.io/badge/node-%E2%89%A520-339933)
 ![Runtime dependencies](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen)
-![Tests](https://img.shields.io/badge/tests-31%20passing-brightgreen)
+![Tests](https://img.shields.io/badge/tests-36%20passing-brightgreen)
 ![Coverage](https://img.shields.io/badge/coverage-92%25%20lines-brightgreen)
 
 [**Documentation site**](https://shahvatsalofficial.github.io/archsutra-ai/) · [Handbook](docs/handbook/README.md) · [**Trust and assurance register**](docs/handbook/13-trust-and-assurance.md) · [Real-world evaluation](docs/handbook/14-real-world-evaluation.md) · [Sample report](examples/brownfield-monolith/sample-output/audit-report.md)
@@ -24,7 +24,7 @@ ArchSutra AI is an open-source **software architecture agent**. It ships portabl
 
 > **No extra API key.** Inside a supported AI IDE, ArchSutra uses that IDE's own model. You need access to the IDE, not to an ArchSutra account. The CLI is offline, read-only by default, and has no telemetry. Optional provider-backed server inference is **not** part of v0.1; if added later it will be opt-in, separately configured, and may cost money.
 
-Created by **[Vatsal Shah](https://github.com/shahvatsalofficial)**. Licensed under Apache-2.0.
+Created by **[Vatsal Shah](https://shahvatsal.com)**. Licensed under Apache-2.0.
 
 ## Contents
 
@@ -38,23 +38,26 @@ Created by **[Vatsal Shah](https://github.com/shahvatsalofficial)**. Licensed un
 | Different answer every run | A deterministic CLI produces reproducible findings with stable rule IDs |
 | Another tool, another key, another bill | Offline CLI; skills run on the model you already use in your IDE |
 | Reviews are slow and rare | First-pass audit in seconds; fits in CI with `--fail-on high` |
-| "Trust me" scanners | Open source, zero runtime dependencies, tests, CI on 3 OSes, accuracy measured on 52 real repositories with the false positives published |
+| "Trust me" scanners | Open source, zero runtime dependencies, tests, CI on Ubuntu and Windows, accuracy measured on 52 real repositories with the false positives published |
 
 ## 60-second start
 
 Requires Node.js 20+.
 
 ```bash
-# audit any repo: offline, no API key. Writes Markdown and HTML.
-npx github:shahvatsalofficial/archsutra-ai audit . --output docs/architecture
+# Windows and npm: this version installs a command named archsutra-ai.
+npx --yes archsutra-ai@0.1.3 audit . --output docs/architecture
 # open docs/architecture/index.html
 
+# or from git (default branch has the same bin; the v0.1.2 tag does not):
+npx github:shahvatsalofficial/archsutra-ai audit . --output docs/architecture
+
 # install the skills into your project for your AI IDE (preview first)
-npx github:shahvatsalofficial/archsutra-ai install --host claude --target . --dry-run
-npx github:shahvatsalofficial/archsutra-ai install --host claude --target .
+npx --yes archsutra-ai@0.1.3 install --host claude --target . --dry-run
+npx --yes archsutra-ai@0.1.3 install --host claude --target .
 ```
 
-For anything beyond a first try, **pin a tag or commit** so the code cannot change under you: `npx github:shahvatsalofficial/archsutra-ai#v0.1.2 audit . --output docs/architecture` (see [supply chain](docs/handbook/15-supply-chain-and-release.md)). Install **one** host per project; several hosts read the same skill folders.
+For anything beyond a first try, **pin a version** so the code cannot change under you. On npm, including Windows: `npx --yes archsutra-ai@0.1.3 audit . --output docs/architecture`. The git tag `v0.1.2` is the attested GitHub release, but that tarball's bin is only `archsutra`, so `npx archsutra-ai` against `v0.1.2` fails on Windows. There is no `v0.1.3` git tag, and the npm `0.1.3` tarball was not built by Actions (no npm provenance). Details: [supply chain](docs/handbook/15-supply-chain-and-release.md). Install **one** host per project; several hosts read the same skill folders.
 
 Without `--output`, `audit` and `map` print one format to the terminal (`--format md` or `--format html`) and write nothing. With `--output`, every report is written as both a Markdown file and an HTML page.
 
@@ -101,7 +104,7 @@ We published the 50% baseline, fixed the false positives it exposed (each has a
 
 | Evidence | Result |
 |---|---|
-| Automated tests (`npm test`) | **31 passed, 0 failed** ([output](docs/proof/test-results.txt)) |
+| Automated tests (`npm test`) | **36 passed, 0 failed** ([output](docs/proof/test-results.txt)) |
 | Test coverage | 92% lines, 81% branches, 91% functions ([report](docs/proof/coverage.txt)) |
 | CI matrix | Ubuntu and Windows x Node 20, 22, 24 plus Ubuntu on the newest Node ([Actions](https://github.com/shahvatsalofficial/archsutra-ai/actions)). macOS is not in CI: GitHub cancelled those jobs before a runner started, and there is no Mac available to re-check them |
 | Robustness | ReDoS guard, hostile file names, binary files, path traversal, symlinks, byte and file budgets, all tested |
@@ -112,7 +115,7 @@ We published the 50% baseline, fixed the false positives it exposed (each has a
 
 ### Not yet proven (we say so)
 
-Live behavior inside each AI IDE (layouts match vendor docs; [smoke-test protocol](docs/compatibility/smoke-tests/README.md) is open for results), an independent security review, a head-to-head comparison with other scanners (workflow ready, not yet run), trademark clearance for the name, and a lawyer's review of these documents. No OpenSSF Scorecard result exists until the first run; none is quoted.
+Live behavior inside each AI IDE (layouts match vendor docs; [smoke-test protocol](docs/compatibility/smoke-tests/README.md) is open for results), an independent security review, a head-to-head comparison with other scanners (workflow ready, not yet run), trademark clearance for the name, and a lawyer's review of these documents. OpenSSF Scorecard scored this repository **5.7 / 10** on 2026-11-06 (Scorecard v5.6.0, commit `06c87c4`). That score is real and low: branch protection, code review, signed-releases (as Scorecard counts them), fuzzing, and the Best Practices badge are 0. Quote the score with those zeros, not as a pass.
 
 ## Sample output
 
@@ -174,21 +177,24 @@ Real sub-agent spawning depends on the host. Where unavailable, Prime performs t
 ## CLI reference
 
 ```text
-archsutra init|doctor|map|audit|verify|export [path]
+archsutra init|doctor|map|audit|review|design|threat-model|modernize|cost|verify|export [path]
+archsutra drift|compare <before.json> <after.json>
+archsutra drift|compare [path] --baseline <findings.json>
 archsutra html <file.md>
+archsutra mcp
 archsutra install|uninstall --host <claude|cursor|codex|copilot|gemini> [--target dir] [--dry-run] [--force]
 archsutra hosts
-Flags: --json  --format <md|html>  --dry-run  --output <dir>  --fail-on <critical|high|medium|low>  --verbose  --version  --help
+Flags: --json  --format <md|html>  --dry-run  --output <dir>  --baseline <file>  --fail-on <critical|high|medium|low>  --verbose  --version  --help
 ```
 
-Exit codes: `0` ok, `1` findings at or above `--fail-on` / install conflict / failed doctor, `2` usage error, `3` command needs a model (use the skill), `4` verification failed, `5` internal error.
+Exit codes: `0` ok, `1` findings at or above `--fail-on` / install conflict / failed doctor, `2` usage error, `3` reserved, `4` verification failed, `5` internal error.
 
-`design`, `review`, `threat-model`, `modernize`, `compare`, `cost` and `drift` need semantic reasoning, so the CLI exits `3` and points you to the matching skill. It never pretends a parser can reason and never calls a model API. Full reference: [CLI reference](docs/handbook/06-cli-reference.md). Rule list: [rule catalog](docs/handbook/12-rule-catalog.md).
+`design`, `review`, `threat-model`, `modernize`, `cost`, `compare`, and `drift` run offline. They write evidence starters. Sections a parser cannot decide stay marked `unknown`. The IDE skill fills those. No model API is called. `compare` diffs two ArchSutra findings files. Semgrep overlap is `node scripts/compare.mjs` and is not run by the CLI. Full reference: [CLI reference](docs/handbook/06-cli-reference.md). Rule list: [rule catalog](docs/handbook/12-rule-catalog.md).
 
 ## Use it in CI
 
 ```yaml
-- run: npx --yes github:shahvatsalofficial/archsutra-ai#v0.1.2 audit . --fail-on high
+- run: npx --yes archsutra-ai@0.1.3 audit . --fail-on high
 ```
 
 Upload SARIF to GitHub code scanning: see the [user guide](docs/handbook/05-user-guide.md). Start with `--fail-on critical` on an existing codebase and tighten later; roughly half of valid findings need no action.
@@ -231,7 +237,8 @@ When you use the skills, **your AI IDE's model provider** processes your prompts
 - Static, heuristic rules: expect false positives and false negatives; every finding lists caveats, and about half of valid findings are not worth acting on.
 - Import graph covers JS/TS and Python. Other languages are detected but not graphed.
 - Reliability, performance, scalability, data integrity and cost are `not assessed` without runtime evidence.
-- Adapters are not yet verified in live hosts. Not published to npm (use the `npx github:` path).
+- Adapters are not yet verified in live hosts.
+- npm package `archsutra-ai` is published (`0.1.2` and `0.1.3`). `0.1.3` adds the `archsutra-ai` command name for Windows. It has no git tag and no npm provenance. The name `archsutra` (no `-ai`) was still unclaimed on 2026-11-06. Do not publish the stub in the parent folder.
 
 ## FAQ
 
@@ -260,7 +267,8 @@ More: [glossary and FAQ](docs/handbook/11-glossary-and-faq.md).
 - [ ] Suppression/baseline file for accepted findings
 - [ ] Independent security review; trademark clearance; legal review
 - [ ] Optional local-model and bring-your-own-key server mode, strictly opt-in
-- [ ] npm publication after name and trademark checks
+- [x] npm package `archsutra-ai` published (`0.1.2`, `0.1.3`) — laptop publish, no provenance, no `v0.1.3` tag
+- [ ] npm publish from GitHub Actions with provenance, one digest shared with the GitHub release (`v0.1.4` or later; `0.1.3` cannot be replaced)
 
 Full plan with acceptance tests: [roadmap](docs/handbook/09-compatibility-and-roadmap.md). Starter tasks: [good first issues](docs/community/good-first-issues.md).
 

package/dist/audit.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { readLines, walk } from './fsutil.js';
 import { buildMap, readJson } from './map.js';
+import { isSuppressed, loadSuppressions } from './suppress.js';
 import { DEV_TOOLING_PATH, TEST_PATH, commentMask, isDataLike, isMinified, isVendoredPath, looksThirdParty } from './heuristics.js';
 import { detectSecrets, excerpt } from './redact.js';
 const CODE_EXT = new Set([
@@ -474,8 +475,10 @@ export async function runAudit(root, corpusIn) {
     }
     // ---- Assign stable IDs ------------------------------------------------
     const sevOrder = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
-    drafts.sort((a, b) => sevOrder[a.severity] - sevOrder[b.severity] || a.rule.localeCompare(b.rule));
-    const findings = drafts.map((x, i) => ({ ...x, id: `${x.rule}#${String(i + 1).padStart(3, '0')}`, status: 'open' }));
+    const suppressions = await loadSuppressions(root);
+    const visible = drafts.filter((d) => !isSuppressed(d, suppressions));
+    visible.sort((a, b) => sevOrder[a.severity] - sevOrder[b.severity] || a.rule.localeCompare(b.rule));
+    const findings = visible.map((x, i) => ({ ...x, id: `${x.rule}#${String(i + 1).padStart(3, '0')}`, status: 'open' }));
     return { map, findings, scorecard: scorecard(findings, codeCount), failedChecks };
 }
 function scorecard(findings, codeCount) {

package/dist/cli.js

@@ -7,9 +7,11 @@ import { exists } from './fsutil.js';
 import { buildMap } from './map.js';
 import { markdownTitle, renderAuditHtml, renderCurrentStateHtml, renderMarkdownHtml, renderOverviewHtml } from './html.js';
 import { findingsJson, registerJson, renderAuditReport, renderCurrentState, renderOverview, renderSarif } from './report.js';
+import { diffFindings, renderDrift } from './drift.js';
+import { serveMcp } from './mcp.js';
+import { renderCost, renderDesign, renderModernize, renderReview, renderThreatModel } from './scaffold.js';
 import { verifyProject } from './verify.js';
 const EXIT = { ok: 0, findings: 1, usage: 2, needsModel: 3, verifyFailed: 4, error: 5 };
-const MODEL_COMMANDS = ['design', 'review', 'threat-model', 'modernize', 'compare', 'cost', 'drift'];
 const HELP = `ArchSutra AI - Design. Audit. Evolve.
 
 Usage: archsutra <command> [path] [options]
@@ -19,33 +21,41 @@ Deterministic commands (no AI, no network, read-only unless noted):
   doctor [path]      check Node, hosts, installed files, conflicts
   map [path]         reverse-engineer modules, dependencies, cycles
   audit [path]       evidence-linked findings + scorecard
+  review [path]      same evidence as audit, written as a review starter
+  design [path]      design starter from the module map; decisions stay unknown
+  threat-model [path] STRIDE starter from security findings; the rest stays unknown
+  modernize [path]   one slice per finding; target architecture stays unknown
+  cost [path]        states that cost is not assessed
+  drift              diff two findings.json files, or a project against --baseline
+  compare            same diff as drift, for two ArchSutra snapshots
   verify [path]      validate skills, agents, links, diagrams, findings.json
   export [path]      write every report as Markdown and HTML (use --output)
   html <file.md>     write a readable HTML page next to a Markdown report
+  mcp                MCP server on stdio (tools: audit, map, drift)
   install            install skills/agents into a project (--host, --target)
   uninstall          remove files ArchSutra installed (--host, --target)
   hosts              list adapters and their support level
 
-Model-backed workflows (${MODEL_COMMANDS.join(', ')}):
-  Run these through the ArchSutra skills inside your AI IDE.
+Semantic judgment (options, STRIDE completion, spend) stays marked unknown.
+Run the matching skill in your IDE to fill those sections. No model API is called.
 
 Options:
   --json             machine-readable output
   --format <md|html> stdout format for audit and map when not writing files (default md)
   --dry-run          show what would change; write nothing
-  --output <dir>     directory for audit, map and export (export default docs/architecture).
-                     audit and map write Markdown and HTML together. For html, a .html file path.
+  --output <dir>     directory for audit, map, export, and the starter commands
+  --baseline <file>  findings.json to diff against (drift, compare)
   --host <id>        claude | cursor | codex | copilot | gemini
   --target <dir>     project to install into (default .)
   --force            overwrite modified files (backups kept)
-  --fail-on <sev>    audit exits 1 if a finding is at or above: critical|high|medium|low
+  --fail-on <sev>    audit, review, and drift exit 1 at or above this severity
   --verbose          extra detail
   --version, --help
 `;
 function parse(argv) {
     const flags = {};
     const pos = [];
-    const withValue = new Set(['output', 'host', 'target', 'fail-on', 'format']);
+    const withValue = new Set(['output', 'host', 'target', 'fail-on', 'format', 'baseline']);
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a.startsWith('--')) {
@@ -94,6 +104,22 @@ async function writeReportFiles(outDir, files, dry) {
 function wroteLine(dry, outDir, files, hint) {
     return `${dry ? 'Would write' : 'Wrote'} ${files.length} files to ${outDir}\n${files.map((f) => `  ${f.path}`).join('\n')}\n${hint}`;
 }
+async function readFindings(file) {
+    const raw = JSON.parse(await fs.readFile(file, 'utf8'));
+    const list = Array.isArray(raw) ? raw : raw.findings;
+    if (!Array.isArray(list))
+        throw new Error(`${file} has no findings array`);
+    return list;
+}
+function severityExit(findings, th) {
+    if (!th)
+        return undefined;
+    const order = ['critical', 'high', 'medium', 'low', 'info'];
+    const i = order.indexOf(th);
+    if (i < 0)
+        return EXIT.usage;
+    return findings.some((f) => order.indexOf(f.severity) <= i) ? EXIT.findings : EXIT.ok;
+}
 async function main() {
     const args = parse(process.argv.slice(2));
     const json = Boolean(args.flags.json);
@@ -262,14 +288,92 @@ async function main() {
             out(json, { ...res, dryRun: dry }, `${dry ? 'DRY RUN\n' : ''}removed: ${res.removed.length}\n${res.removed.map((r) => `  - ${r}`).join('\n')}${res.kept.length ? `\nkept (modified by you): \n${res.kept.map((r) => `  - ${r}`).join('\n')}` : ''}`);
             return EXIT.ok;
         }
-        default:
-            if (MODEL_COMMANDS.includes(args.cmd)) {
-                const msg = `"${args.cmd}" needs semantic reasoning, which a deterministic CLI cannot do honestly.\nRun it inside your AI IDE through the matching ArchSutra skill (install with: archsutra install --host <id>).\nNo API call was made.`;
-                out(json, { command: args.cmd, requiresModel: true, message: msg }, msg);
-                return EXIT.needsModel;
+        case 'mcp': {
+            await serveMcp();
+            return EXIT.ok;
+        }
+        case 'drift':
+        case 'compare': {
+            let before;
+            let after;
+            if (args.flags.baseline) {
+                before = await readFindings(path.resolve(String(args.flags.baseline)));
+                after = (await runAudit(target)).findings;
+            }
+            else if (args.pos.length >= 2) {
+                before = await readFindings(path.resolve(args.pos[0]));
+                after = await readFindings(path.resolve(args.pos[1]));
+            }
+            else {
+                process.stderr.write(`${args.cmd} needs two findings.json files, or a project path and --baseline <findings.json>.\nSemgrep overlap stays in scripts/compare.mjs. This command does not download rules or clone repositories.\n`);
+                return EXIT.usage;
+            }
+            const report = diffFindings(before, after);
+            const title = args.cmd === 'compare' ? 'Findings comparison' : 'Architecture drift';
+            const note = args.cmd === 'compare' ? '\nSemgrep overlap is scripts/compare.mjs (needs semgrep on PATH). Not run by this command.\n' : '';
+            const md = `${renderDrift(report, title)}${note}`;
+            if ('output' in args.flags) {
+                const outDir = insideProject(path.resolve(args.pos[0] ?? '.'), String(args.flags.output || 'docs/architecture'));
+                if (!outDir) {
+                    process.stderr.write('--output must stay inside the project directory.\n');
+                    return EXIT.usage;
+                }
+                const files = [
+                    { path: `${args.cmd}.md`, content: md },
+                    { path: `${args.cmd}.html`, content: renderMarkdownHtml(md, title) },
+                ];
+                await writeReportFiles(outDir, files, dry);
+            }
+            out(json, report, md);
+            const added = report.added.map((r) => ({ severity: (r.after ?? 'info') }));
+            const gate = severityExit(added, args.flags['fail-on']);
+            if (gate === EXIT.usage) {
+                process.stderr.write(`Invalid --fail-on "${args.flags['fail-on']}"\n`);
+                return EXIT.usage;
+            }
+            return gate ?? EXIT.ok;
+        }
+        case 'review':
+        case 'design':
+        case 'threat-model':
+        case 'modernize':
+        case 'cost': {
+            const res = await runAudit(target);
+            const md = args.cmd === 'review' ? renderReview(res)
+                : args.cmd === 'design' ? renderDesign(res)
+                    : args.cmd === 'threat-model' ? renderThreatModel(res)
+                        : args.cmd === 'modernize' ? renderModernize(res)
+                            : renderCost(res);
+            if ('output' in args.flags) {
+                const outDir = insideProject(target, String(args.flags.output || 'docs/architecture'));
+                if (!outDir) {
+                    process.stderr.write('--output must stay inside the project directory.\n');
+                    return EXIT.usage;
+                }
+                const files = [
+                    { path: `${args.cmd}.md`, content: md },
+                    { path: `${args.cmd}.html`, content: renderMarkdownHtml(md, args.cmd) },
+                ];
+                await writeReportFiles(outDir, files, dry);
+                out(json, { dryRun: dry, command: args.cmd }, wroteLine(dry, outDir, files, 'Unknown sections stay unknown. The IDE skill fills those.'));
+            }
+            else {
+                out(json, { command: args.cmd, markdown: md }, md);
+            }
+            if (args.cmd === 'review') {
+                const gate = severityExit(res.findings, args.flags['fail-on']);
+                if (gate === EXIT.usage) {
+                    process.stderr.write(`Invalid --fail-on "${args.flags['fail-on']}"\n`);
+                    return EXIT.usage;
+                }
+                return gate ?? EXIT.ok;
             }
+            return EXIT.ok;
+        }
+        default: {
             process.stderr.write(`Unknown command "${args.cmd}".\n${HELP}`);
             return EXIT.usage;
+        }
     }
 }
 main().then((code) => {

package/dist/drift.js

@@ -0,0 +1,57 @@
+function keyOf(f) {
+    const paths = [...new Set(f.evidence.map((e) => e.path))].sort();
+    const path = paths[0] ?? '.';
+    return { key: `${f.rule}@${paths.join('|') || '.'}`, path };
+}
+/** Diff two findings lists. Identity is rule plus evidence paths, not the generated sequence id. */
+export function diffFindings(before, after) {
+    const prev = new Map();
+    const next = new Map();
+    for (const f of before) {
+        const k = keyOf(f);
+        prev.set(k.key, { sev: f.severity, path: k.path, rule: f.rule });
+    }
+    for (const f of after) {
+        const k = keyOf(f);
+        next.set(k.key, { sev: f.severity, path: k.path, rule: f.rule });
+    }
+    const added = [];
+    const removed = [];
+    const changed = [];
+    for (const [key, row] of next) {
+        const old = prev.get(key);
+        if (!old)
+            added.push({ key, rule: row.rule, path: row.path, after: row.sev });
+        else if (old.sev !== row.sev)
+            changed.push({ key, rule: row.rule, path: row.path, before: old.sev, after: row.sev });
+    }
+    for (const [key, row] of prev) {
+        if (!next.has(key))
+            removed.push({ key, rule: row.rule, path: row.path, before: row.sev });
+    }
+    const byKey = (a, b) => a.key.localeCompare(b.key);
+    added.sort(byKey);
+    removed.sort(byKey);
+    changed.sort(byKey);
+    return { added, removed, changed };
+}
+export function renderDrift(report, title) {
+    const line = (r) => `- ${r.rule} ${r.path}${r.before ? ` ${r.before}` : ''}${r.before && r.after ? ' ->' : ''} ${r.after ?? ''}`.replace(/\s+/g, ' ').trim();
+    return [
+        `# ${title}`,
+        '',
+        'Deterministic diff of two ArchSutra findings files. This is not a Semgrep comparison and not a model review.',
+        '',
+        `Added: ${report.added.length}. Removed: ${report.removed.length}. Severity changed: ${report.changed.length}.`,
+        '',
+        '## Added',
+        report.added.length ? report.added.map(line).join('\n') : '_None._',
+        '',
+        '## Removed',
+        report.removed.length ? report.removed.map(line).join('\n') : '_None._',
+        '',
+        '## Severity changed',
+        report.changed.length ? report.changed.map(line).join('\n') : '_None._',
+        '',
+    ].join('\n');
+}

package/dist/imports.js

@@ -0,0 +1,42 @@
+/** Longest known module path that is a suffix of an import. Stdlib names only match when a repo module is actually named that. */
+export function moduleForImport(spec, moduleNames) {
+    const norm = spec.replace(/::/g, '/').replace(/\./g, '/').replace(/^\/+|\/+$/g, '');
+    const parts = norm.split('/').filter((p) => p && p !== 'crate' && p !== 'super' && p !== 'self');
+    let best;
+    for (let i = 0; i < parts.length; i++) {
+        const suffix = parts.slice(i).join('/');
+        for (const cand of [suffix, `src/${suffix}`]) {
+            if (moduleNames.has(cand) && (best === undefined || cand.length > best.length))
+                best = cand;
+        }
+    }
+    return best;
+}
+const GO_IMPORT = /"([^"]+)"/g;
+const DOT_IMPORT = /^\s*import\s+(?:static\s+)?([A-Za-z_][\w.]*)/;
+const CS_USING = /^\s*using\s+(?:static\s+)?([A-Za-z_][\w.]*)\s*;/;
+const RUST_USE = /^\s*(?:pub\s+)?use\s+([A-Za-z_][\w:]*)/;
+const RUST_MOD = /^\s*(?:pub\s+)?mod\s+([A-Za-z_][\w]*)\s*;/;
+export function importSpecs(ext, line, fromRel) {
+    if (ext === '.go')
+        return [...line.matchAll(GO_IMPORT)].map((m) => m[1]).filter((s) => s.includes('/'));
+    if (ext === '.java' || ext === '.kt') {
+        const m = DOT_IMPORT.exec(line);
+        return m ? [m[1]] : [];
+    }
+    if (ext === '.cs') {
+        const m = CS_USING.exec(line);
+        return m ? [m[1]] : [];
+    }
+    if (ext === '.rs') {
+        const use = RUST_USE.exec(line);
+        if (use)
+            return [use[1]];
+        const mod = RUST_MOD.exec(line);
+        if (!mod)
+            return [];
+        const dir = fromRel.split('/').slice(0, -1).join('/');
+        return [dir ? `${dir}/${mod[1]}` : mod[1]];
+    }
+    return [];
+}

package/dist/map.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { readLines, walk } from './fsutil.js';
 import { TEST_PATH, commentMask } from './heuristics.js';
+import { importSpecs, moduleForImport } from './imports.js';
 import { excerpt } from './redact.js';
 const ECOSYSTEM_BY_EXT = {
     '.ts': 'TypeScript', '.tsx': 'TypeScript', '.js': 'JavaScript', '.jsx': 'JavaScript', '.mjs': 'JavaScript',
@@ -206,6 +207,17 @@ export async function buildMap(root, corpus) {
                         addEdge(cand, i + 1, text);
             });
         }
+        else if (f.ext === '.go' || f.ext === '.java' || f.ext === '.kt' || f.ext === '.cs' || f.ext === '.rs') {
+            lines.forEach((text, i) => {
+                if (cmask[i])
+                    return;
+                for (const spec of importSpecs(f.ext, text, f.rel)) {
+                    const to = moduleForImport(spec, moduleNames);
+                    if (to)
+                        addEdge(to, i + 1, text);
+                }
+            });
+        }
         else {
             blind.add(`Import graph not implemented for ${eco}; module dependencies are not computed for those files.`);
         }
@@ -226,7 +238,7 @@ export async function buildMap(root, corpus) {
     if (c.skipped.symlinks)
         blind.add(`${c.skipped.symlinks} symlink(s) were not followed.`);
     blind.add('Runtime behaviour, deployed topology, and data volumes are not observable from source alone.');
-    blind.add('Dependency edges are module-level and based on relative imports; dynamic imports and DI wiring may be missed.');
+    blind.add('Dependency edges are module-level. JS/TS uses relative imports. Python uses the top package name. Go, Java, Kotlin, C#, and Rust match an import suffix to a module path. Dynamic imports, path aliases, and DI wiring may be missed. PHP, Ruby, Swift, and Dart are detected and not graphed.');
     const sortedEco = [...ecosystems].sort((a, b) => (ecoCount.get(b) ?? 0) - (ecoCount.get(a) ?? 0));
     return {
         root: c.root,

package/dist/mcp.js

@@ -0,0 +1,81 @@
+import { readFile } from 'node:fs/promises';
+import { runAudit } from './audit.js';
+import { diffFindings } from './drift.js';
+import { buildMap } from './map.js';
+import { findingsJson } from './report.js';
+const TOOLS = [
+    { name: 'archsutra_audit', description: 'Offline architecture audit. Returns findings JSON. Read-only. No network.', inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] } },
+    { name: 'archsutra_map', description: 'Offline module map: ecosystems, edges, cycles, blind spots. Read-only.', inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] } },
+    { name: 'archsutra_drift', description: 'Diff two findings.json files already on disk.', inputSchema: { type: 'object', properties: { before: { type: 'string' }, after: { type: 'string' } }, required: ['before', 'after'] } },
+];
+function frame(obj) {
+    const body = JSON.stringify(obj);
+    return `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`;
+}
+async function callTool(name, args) {
+    if (name === 'archsutra_audit') {
+        const res = await runAudit(String(args.path ?? '.'));
+        return JSON.stringify(findingsJson(res));
+    }
+    if (name === 'archsutra_map') {
+        return JSON.stringify(await buildMap(String(args.path ?? '.')));
+    }
+    if (name === 'archsutra_drift') {
+        const before = JSON.parse(await import('node:fs/promises').then((fs) => fs.readFile(String(args.before), 'utf8')));
+        const after = JSON.parse(await import('node:fs/promises').then((fs) => fs.readFile(String(args.after), 'utf8')));
+        const b = Array.isArray(before) ? before : before.findings;
+        const a = Array.isArray(after) ? after : after.findings;
+        return JSON.stringify(diffFindings(b, a));
+    }
+    throw new Error(`Unknown tool ${name}`);
+}
+/** Speak MCP over stdio (Content-Length framing). One process, then exit when stdin closes. */
+export async function serveMcp() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    const buf = Buffer.concat(chunks);
+    let offset = 0;
+    const text = buf.toString('utf8');
+    while (offset < text.length) {
+        const headerEnd = text.indexOf('\r\n\r\n', offset);
+        if (headerEnd < 0)
+            break;
+        const header = text.slice(offset, headerEnd);
+        const m = /Content-Length:\s*(\d+)/i.exec(header);
+        if (!m)
+            break;
+        const len = Number(m[1]);
+        const start = headerEnd + 4;
+        const body = text.slice(start, start + len);
+        offset = start + len;
+        let msg;
+        try {
+            msg = JSON.parse(body);
+        }
+        catch {
+            continue;
+        }
+        if (msg.id === undefined || msg.id === null)
+            continue;
+        if (msg.method === 'initialize') {
+            const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+            process.stdout.write(frame({ jsonrpc: '2.0', id: msg.id, result: { protocolVersion: '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: 'archsutra', version: pkg.version } } }));
+        }
+        else if (msg.method === 'tools/list') {
+            process.stdout.write(frame({ jsonrpc: '2.0', id: msg.id, result: { tools: TOOLS } }));
+        }
+        else if (msg.method === 'tools/call') {
+            try {
+                const textOut = await callTool(String(msg.params?.name), msg.params?.arguments ?? {});
+                process.stdout.write(frame({ jsonrpc: '2.0', id: msg.id, result: { content: [{ type: 'text', text: textOut }] } }));
+            }
+            catch (e) {
+                process.stdout.write(frame({ jsonrpc: '2.0', id: msg.id, error: { code: -32000, message: e instanceof Error ? e.message : String(e) } }));
+            }
+        }
+        else {
+            process.stdout.write(frame({ jsonrpc: '2.0', id: msg.id, error: { code: -32601, message: `Method not found: ${msg.method}` } }));
+        }
+    }
+}