dagward 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,165 @@
+# Dagward
+
+**Deterministic architecture enforcement for the age of AI coding agents.**
+
+> Your dependency graph should be a DAG. Dagward keeps it one — even when AI agents write the code.
+
+AI agents write undisciplined code that compounds: more abstractions, more context, slower every session. Dagward enforces your rules deterministically and flips the compounding: cleaner structure, smaller context, faster and cheaper every session.
+
+Dagward turns your architecture into something machines must obey:
+
+- **Infer** — Scan your repo, get a draft of your actual module boundaries and dependency rules. Confirm instead of writing from scratch.
+- **Enforce** — Every change is checked against the rules: as a Claude Code hook, pre-commit, and in CI. Checks are deterministic graph queries — no AI judging AI.
+- **Feed back** — Violations return structured feedback the agent can act on: which rule, why it exists, how to fix. Agents correct themselves; humans stay out of the loop.
+- **Exempt with intent** — Real architectures have exceptions. Annotated exemptions are versioned in git and become your team's architecture decision record.
+
+**AI proposes rules. Humans approve them. Machines enforce them.** No line of code's compliance depends on a model's mood.
+
+---
+
+## Quickstart
+
+```bash
+# 1. Infer your architecture (read-only, ~1 min on most repos)
+npx dagward init
+
+# 2. Review the draft — edit dagward.yml, then commit it
+git add dagward.yml && git commit -m "chore: adopt architecture rules"
+
+# 3. Check the whole repo
+npx dagward check
+
+# 4. Wire it into Claude Code (one command)
+npx dagward install-hook claude-code
+```
+
+That's it. From now on, every edit an agent makes is checked against your rules the moment it lands — and violations are fed back to the agent in a format it can act on.
+
+Requirements: Node.js ≥ 20, a TypeScript project with a `tsconfig.json`. Monorepos (npm/pnpm/yarn workspaces) are supported.
+
+## What `init` produces
+
+`dagward init` builds the full dependency graph using the TypeScript compiler API (real module resolution — `paths`, workspace deps, conditional exports), detects strongly connected components and layer structure, and writes two files:
+
+- **`ARCHITECTURE.md`** — a human-readable snapshot of your system as it actually is: layers, module boundaries, existing cycles, and the edges that look accidental. Useful on its own, even if you never adopt the rules.
+- **`dagward.yml`** — a draft rule file. Nothing is enforced until you review, edit, and commit it. Confirming is a 10-minute job; writing from scratch would take days.
+
+## The rule file
+
+Rules are declarative YAML — language-agnostic by design, and readable by both humans and agents. MVP supports three rule types:
+
+```yaml
+version: 1
+
+layers:                      # topological order: earlier may not depend on later
+  - name: domain
+    match: "packages/domain/**"
+  - name: application
+    match: "packages/app/**"
+  - name: infrastructure
+    match: "packages/infra/**"
+
+rules:
+  - id: no-cycles
+    type: no-cycles
+    level: package           # package | file
+    rationale: >
+      Cycles between packages cause initialization-order bugs and make
+      modules impossible to extract or test in isolation.
+
+  - id: layering
+    type: layer-order        # enforces the `layers` list above
+    ignore-type-imports: true
+    rationale: >
+      Domain logic must stay framework-free. Dependencies point inward.
+
+  - id: no-direct-db-from-api
+    type: forbidden-edge
+    from: "packages/api/**"
+    to: "packages/infra/db/**"
+    rationale: >
+      API handlers go through the repository layer (ADR-012, 2024-06).
+      Direct DB access bypassed row-level security once. Never again.
+```
+
+`rationale` is not a comment — it is part of the enforcement. When an agent violates a rule, the rationale is included in the feedback, so the agent understands *why* and fixes the code instead of fighting the rule.
+
+Type-only imports (`import type`) are tracked as a separate edge kind and can be exempted per rule — a type-level cycle is not a runtime cycle, and Dagward knows the difference.
+
+## Checking
+
+```bash
+dagward check                 # full repo
+dagward check --changed       # only files changed since HEAD (fast path for hooks)
+dagward check --format agent  # structured JSON for agent consumption
+```
+
+Checks are pure graph queries — cycle detection via strongly connected components, layer rules as reachability queries on the condensation. Deterministic, reproducible, milliseconds on the incremental path. No network calls, no LLM, no flakiness.
+
+Exit code `0` = clean, `1` = violations, `2` = config error. That's your CI gate:
+
+```yaml
+# .github/workflows/architecture.yml
+- run: npx dagward check --format github
+```
+
+## Agent feedback
+
+With `--format agent`, a violation looks like this:
+
+```json
+{
+  "violations": [{
+    "rule": "no-direct-db-from-api",
+    "severity": "error",
+    "edge": {
+      "from": "packages/api/src/checkout.ts",
+      "to": "packages/infra/db/client.ts",
+      "kind": "value-import"
+    },
+    "rationale": "API handlers go through the repository layer (ADR-012, 2024-06). Direct DB access bypassed row-level security once. Never again.",
+    "fix_direction": "Import from packages/app/repositories instead, or add a repository method if none fits.",
+    "exemption_hint": "If this dependency is intentional, add an annotated exemption — see docs/exemptions.md."
+  }]
+}
+```
+
+The Claude Code hook feeds this back automatically after each edit. In practice, agents fix their own violations on the next turn without human intervention.
+
+## Exemptions
+
+Real architectures have exceptions. Unexplained exceptions are how architectures rot — so every exemption requires a reason, and lives in git:
+
+```yaml
+exemptions:
+  - rule: layering
+    from: "packages/domain/src/legacy/pricing.ts"
+    to: "packages/infra/feature-flags/**"
+    reason: "Pre-dates the flag abstraction. Tracked in TICKET-4102."
+    added-by: "@yourname"
+    added: 2026-07-19
+```
+
+Over time, your exemption log becomes something no wiki ever stays: an accurate, versioned record of every architectural decision and its debt.
+
+## What Dagward is not
+
+- **Not a linter.** Linters check code style within a file. Dagward checks the structure between files — the part no single diff reveals and no agent context window retains.
+- **Not an AI reviewer.** Review bots use an LLM to judge LLM output — probabilistic opinions about probabilistic code. Dagward's enforcement is a graph query. Same input, same answer, every time.
+- **Not a replacement for CI, tests, or review.** It is one more deterministic gate — the one specifically shaped for the failure mode AI agents actually have.
+
+## Roadmap
+
+- **v0.2 — MCP server**: read-only architecture tools (`check_change`, `query_dependencies`, `explain_rule`) so agents can consult the rules *before* writing code, and interactive rule inference inside your agent session.
+- **v0.3 — Cursor hook**, watch mode, richer rule types (public-API surfaces, tag-based boundaries).
+- **Later**: Python analyzer (same rule format, pluggable analyzer), team features (exemption approval flow, drift trends).
+
+Multi-language support is a design constraint from day one: the rule format and engine are language-agnostic; only the analyzer is TypeScript-specific.
+
+## Status
+
+Early. Dagward currently guards its own repository and a handful of production monorepos. Expect sharp edges; expect fast fixes. Issues and violation war stories are equally welcome.
+
+## License
+
+Apache-2.0. The `Dagward` name and logo are trademarks of the project and are not covered by the code license.

package/dist/cli.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+import { buildFileGraph } from "./fileGraph.js";
+import { buildFolderGraph } from "./folderGraph.js";
+import { buildFunctionGraph } from "./functionGraph.js";
+import { serializeGraph } from "./graph.js";
+import { ConfigError, loadProject } from "./project.js";
+import { renderArchitectureMd } from "./report.js";
+const HELP = `dagward — multi-level dependency graphs for TypeScript projects
+
+Usage:
+  dagward graph [dir] [options]   Analyze the project and write graphs + report
+  dagward init  [dir] [options]   Alias of \`graph\` (rule inference coming later)
+
+Options:
+  --project <path>   Explicit tsconfig.json (default: nearest to [dir])
+  --out <dir>        Output directory (default: <dir>/dagward-out)
+  --help             Show this help
+  --version          Show version
+
+Outputs: graph.folders.json, graph.files.json, graph.functions.json, ARCHITECTURE.md
+
+Exit codes: 0 ok, 2 config error.`;
+function version() {
+    const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    return pkg.version;
+}
+export function main(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: {
+            project: { type: "string" },
+            out: { type: "string" },
+            help: { type: "boolean" },
+            version: { type: "boolean" },
+        },
+        allowPositionals: true,
+    });
+    if (values.help) {
+        console.log(HELP);
+        return 0;
+    }
+    if (values.version) {
+        console.log(version());
+        return 0;
+    }
+    const [command, dirArg] = positionals;
+    if (command !== "graph" && command !== "init") {
+        console.error(command ? `Unknown command: ${command}` : HELP);
+        return command ? 2 : 0;
+    }
+    if (command === "init") {
+        console.error("Note: `init` currently behaves like `graph`; rule inference is coming later.");
+    }
+    const targetDir = path.resolve(dirArg ?? ".");
+    const outDir = path.resolve(values.out ?? path.join(targetDir, "dagward-out"));
+    let project;
+    try {
+        project = loadProject(targetDir, values.project ? path.resolve(values.project) : undefined);
+    }
+    catch (error) {
+        if (error instanceof ConfigError) {
+            console.error(`Config error: ${error.message}`);
+            return 2;
+        }
+        throw error;
+    }
+    console.error(`Analyzing ${project.sourceFiles.length} files (tsconfig at ${project.rootDir})`);
+    const { graph: files, skippedDynamicImports } = buildFileGraph(project);
+    const folders = buildFolderGraph(files);
+    const functions = buildFunctionGraph(project);
+    fs.mkdirSync(outDir, { recursive: true });
+    fs.writeFileSync(path.join(outDir, "graph.folders.json"), serializeGraph(folders));
+    fs.writeFileSync(path.join(outDir, "graph.files.json"), serializeGraph(files));
+    fs.writeFileSync(path.join(outDir, "graph.functions.json"), serializeGraph(functions));
+    fs.writeFileSync(path.join(outDir, "ARCHITECTURE.md"), renderArchitectureMd({ folders, files, functions, skippedDynamicImports, version: version() }));
+    for (const graph of [folders, files, functions]) {
+        const cycles = graph.cycles.length > 0 ? `${graph.cycles.length} cycle(s)!` : "no cycles";
+        console.error(`  ${graph.level}: ${graph.nodes.length} nodes, ${graph.edges.length} edges, ${cycles}`);
+    }
+    console.error(`Wrote 4 files to ${outDir}`);
+    return 0;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    process.exit(main(process.argv.slice(2)));
+}

package/dist/folderGraph.js

@@ -0,0 +1,38 @@
+import path from "node:path";
+import { buildGraph } from "./graph.js";
+function folderOf(fileId) {
+    const dir = path.posix.dirname(fileId);
+    return dir === "" ? "." : dir;
+}
+// Folders are the immediate parent of each file. Ancestor rollups are
+// derivable by consumers from the path hierarchy; emitting every ancestor
+// pair would manufacture phantom cycles at higher levels.
+export function buildFolderGraph(fileGraph) {
+    const fileCounts = new Map();
+    for (const node of fileGraph.nodes) {
+        const folder = folderOf(node.id);
+        fileCounts.set(folder, (fileCounts.get(folder) ?? 0) + 1);
+    }
+    const merged = new Map();
+    for (const edge of fileGraph.edges) {
+        const from = folderOf(edge.from);
+        const to = folderOf(edge.to);
+        if (from === to)
+            continue;
+        // dynamic imports are runtime deps: fold into value at folder level
+        const kind = edge.kind === "type" ? "type" : "value";
+        const key = `${from} ${to} ${kind}`;
+        const existing = merged.get(key);
+        if (existing) {
+            existing.weight += edge.weight;
+        }
+        else {
+            merged.set(key, { from, to, kind, weight: edge.weight });
+        }
+    }
+    const nodes = [...fileCounts.entries()].map(([id, fileCount]) => ({
+        id,
+        fileCount,
+    }));
+    return buildGraph("folder", fileGraph.root, nodes, [...merged.values()]);
+}

package/dist/functionGraph.js

@@ -0,0 +1,166 @@
+import ts from "typescript";
+import { buildGraph } from "./graph.js";
+import { relativeId } from "./project.js";
+function className(node) {
+    const parent = node.parent;
+    if (ts.isClassDeclaration(parent) && parent.name)
+        return parent.name.text;
+    return undefined; // class expressions: skipped
+}
+function memberName(node) {
+    if (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name))
+        return node.name.text;
+    return undefined; // computed names: skipped
+}
+function collectFunctions(sourceFiles, rootDir) {
+    const registry = { fnIds: new Map(), declIds: new Map(), nodes: [] };
+    const seenIds = new Set();
+    const register = (fnNode, decls, id, sf) => {
+        registry.fnIds.set(fnNode, id);
+        for (const decl of decls)
+            registry.declIds.set(decl, id);
+        if (!seenIds.has(id)) {
+            seenIds.add(id);
+            const file = relativeId(rootDir, sf.fileName);
+            const { line } = sf.getLineAndCharacterOfPosition(fnNode.getStart(sf));
+            registry.nodes.push({ id, file, line: line + 1 });
+        }
+    };
+    for (const sf of sourceFiles) {
+        const fileId = relativeId(rootDir, sf.fileName);
+        const visit = (node) => {
+            if (ts.isFunctionDeclaration(node) && node.body) {
+                const name = node.name?.text ??
+                    (node.modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)
+                        ? "default"
+                        : undefined);
+                if (name)
+                    register(node, [node], `${fileId}#${name}`, sf);
+            }
+            else if (ts.isMethodDeclaration(node) && node.body) {
+                const cls = className(node);
+                const member = memberName(node);
+                if (cls && member)
+                    register(node, [node], `${fileId}#${cls}.${member}`, sf);
+            }
+            else if ((ts.isGetAccessor(node) || ts.isSetAccessor(node)) && node.body) {
+                const cls = className(node);
+                const member = memberName(node);
+                if (cls && member)
+                    register(node, [node], `${fileId}#${cls}.${member}`, sf);
+            }
+            else if (ts.isConstructorDeclaration(node) && node.body) {
+                const cls = className(node);
+                // ClassDeclaration mapped too, so `new C()` resolves to the ctor
+                if (cls)
+                    register(node, [node, node.parent], `${fileId}#${cls}.constructor`, sf);
+            }
+            else if (ts.isVariableDeclaration(node) &&
+                ts.isIdentifier(node.name) &&
+                node.initializer &&
+                (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer))) {
+                register(node.initializer, [node, node.initializer], `${fileId}#${node.name.text}`, sf);
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(sf);
+    }
+    return registry;
+}
+function isInImportOrExportClause(node) {
+    const parent = node.parent;
+    return (ts.isImportSpecifier(parent) ||
+        ts.isExportSpecifier(parent) ||
+        ts.isImportClause(parent) ||
+        ts.isNamespaceImport(parent) ||
+        ts.isImportEqualsDeclaration(parent));
+}
+// `: Greeter`, `typeof f`, `extends Base` are not function references
+function isInTypePosition(node) {
+    const parent = node.parent;
+    return (ts.isTypeReferenceNode(parent) ||
+        ts.isTypeQueryNode(parent) ||
+        ts.isExpressionWithTypeArguments(parent) ||
+        ts.isQualifiedName(parent));
+}
+export function buildFunctionGraph(project) {
+    const { checker, rootDir, sourceFiles } = project;
+    const registry = collectFunctions(sourceFiles, rootDir);
+    const merged = new Map();
+    const syntheticModuleNodes = new Map();
+    const callerOf = (node, fileId) => {
+        for (let current = node.parent; current; current = current.parent) {
+            const id = registry.fnIds.get(current);
+            if (id)
+                return id;
+        }
+        const moduleId = `${fileId}#<module>`;
+        if (!syntheticModuleNodes.has(moduleId)) {
+            syntheticModuleNodes.set(moduleId, { id: moduleId, file: fileId, line: 1 });
+        }
+        return moduleId;
+    };
+    const resolveTarget = (call) => {
+        const signatureDecl = checker.getResolvedSignature(call)?.declaration;
+        if (signatureDecl) {
+            const id = registry.declIds.get(signatureDecl);
+            if (id)
+                return id;
+        }
+        let symbol = checker.getSymbolAtLocation(call.expression);
+        if (symbol && symbol.flags & ts.SymbolFlags.Alias) {
+            symbol = checker.getAliasedSymbol(symbol);
+        }
+        for (const decl of symbol?.declarations ?? []) {
+            const id = registry.declIds.get(decl);
+            if (id)
+                return id;
+        }
+        return undefined; // interface methods, node_modules, dynamic dispatch: no edge
+    };
+    const addEdge = (from, to, kind, sf, at) => {
+        const key = `${from} ${to} ${kind}`;
+        const existing = merged.get(key);
+        if (existing) {
+            existing.weight++;
+        }
+        else {
+            const { line } = sf.getLineAndCharacterOfPosition(at.getStart(sf));
+            merged.set(key, { from, to, kind, weight: 1, line: line + 1 });
+        }
+    };
+    for (const sf of sourceFiles) {
+        const fileId = relativeId(rootDir, sf.fileName);
+        const consumedCallees = new Set();
+        const visit = (node) => {
+            if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+                consumedCallees.add(node.expression);
+                const target = resolveTarget(node);
+                if (target)
+                    addEdge(callerOf(node, fileId), target, "call", sf, node);
+            }
+            else if (ts.isIdentifier(node) &&
+                !consumedCallees.has(node) &&
+                node.parent.name !== node &&
+                !isInImportOrExportClause(node) &&
+                !isInTypePosition(node)) {
+                // functions passed as values, e.g. arr.map(fn)
+                let symbol = checker.getSymbolAtLocation(node);
+                if (symbol && symbol.flags & ts.SymbolFlags.Alias) {
+                    symbol = checker.getAliasedSymbol(symbol);
+                }
+                for (const decl of symbol?.declarations ?? []) {
+                    const id = registry.declIds.get(decl);
+                    if (id) {
+                        addEdge(callerOf(node, fileId), id, "reference", sf, node);
+                        break;
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(sf);
+    }
+    const nodes = [...registry.nodes, ...syntheticModuleNodes.values()];
+    return buildGraph("function", rootDir, nodes, [...merged.values()]);
+}

package/dist/graph.js

@@ -0,0 +1,88 @@
+// Iterative Tarjan: explicit frames so deep DFS chains on large repos
+// don't overflow the call stack. Returns SCCs as arrays of node ids.
+export function stronglyConnectedComponents(nodeIds, adjacency) {
+    const index = new Map();
+    const lowlink = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const components = [];
+    let counter = 0;
+    for (const start of nodeIds) {
+        if (index.has(start))
+            continue;
+        const frames = [{ node: start, cursor: 0 }];
+        index.set(start, counter);
+        lowlink.set(start, counter);
+        counter++;
+        stack.push(start);
+        onStack.add(start);
+        while (frames.length > 0) {
+            const frame = frames[frames.length - 1];
+            const neighbors = adjacency.get(frame.node) ?? [];
+            if (frame.cursor < neighbors.length) {
+                const next = neighbors[frame.cursor++];
+                if (!index.has(next)) {
+                    index.set(next, counter);
+                    lowlink.set(next, counter);
+                    counter++;
+                    stack.push(next);
+                    onStack.add(next);
+                    frames.push({ node: next, cursor: 0 });
+                }
+                else if (onStack.has(next)) {
+                    lowlink.set(frame.node, Math.min(lowlink.get(frame.node), index.get(next)));
+                }
+            }
+            else {
+                frames.pop();
+                const parent = frames[frames.length - 1];
+                if (parent) {
+                    lowlink.set(parent.node, Math.min(lowlink.get(parent.node), lowlink.get(frame.node)));
+                }
+                if (lowlink.get(frame.node) === index.get(frame.node)) {
+                    const component = [];
+                    let popped;
+                    do {
+                        popped = stack.pop();
+                        onStack.delete(popped);
+                        component.push(popped);
+                    } while (popped !== frame.node);
+                    components.push(component.sort());
+                }
+            }
+        }
+    }
+    return components;
+}
+// A component is a cycle if it has >1 node, or a single node with a self-edge.
+export function findCycles(nodes, edges) {
+    const adjacency = new Map();
+    for (const edge of edges) {
+        let targets = adjacency.get(edge.from);
+        if (!targets)
+            adjacency.set(edge.from, (targets = []));
+        targets.push(edge.to);
+    }
+    const selfLoops = new Set(edges.filter((e) => e.from === e.to).map((e) => e.from));
+    const components = stronglyConnectedComponents(nodes.map((n) => n.id), adjacency);
+    return components
+        .filter((c) => c.length > 1 || selfLoops.has(c[0]))
+        .sort((a, b) => b.length - a.length || a[0].localeCompare(b[0]))
+        .map((c, i) => ({ id: i, nodes: c }));
+}
+// Sorted nodes/edges, no timestamps: output is diffable and deep-comparable.
+export function buildGraph(level, root, nodes, edges) {
+    const sortedNodes = [...nodes].sort((a, b) => a.id.localeCompare(b.id));
+    const sortedEdges = [...edges].sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || a.kind.localeCompare(b.kind));
+    return {
+        version: 1,
+        level,
+        root,
+        nodes: sortedNodes,
+        edges: sortedEdges,
+        cycles: findCycles(sortedNodes, sortedEdges),
+    };
+}
+export function serializeGraph(graph) {
+    return JSON.stringify(graph, null, 2) + "\n";
+}

package/dist/project.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+import ts from "typescript";
+export class ConfigError extends Error {
+}
+export function relativeId(rootDir, fileName) {
+    return path.relative(rootDir, fileName).split(path.sep).join("/");
+}
+export function loadProject(searchDir, explicitConfig) {
+    const configPath = explicitConfig ?? ts.findConfigFile(searchDir, ts.sys.fileExists, "tsconfig.json");
+    if (!configPath || !ts.sys.fileExists(configPath)) {
+        throw new ConfigError(`No tsconfig.json found from ${searchDir}`);
+    }
+    const host = {
+        ...ts.sys,
+        onUnRecoverableConfigFileDiagnostic: (diagnostic) => {
+            throw new ConfigError(ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"));
+        },
+    };
+    const parsed = ts.getParsedCommandLineOfConfigFile(configPath, undefined, host);
+    if (!parsed)
+        throw new ConfigError(`Failed to parse ${configPath}`);
+    const program = ts.createProgram({
+        rootNames: parsed.fileNames,
+        options: parsed.options,
+        projectReferences: parsed.projectReferences,
+    });
+    const sourceFiles = program
+        .getSourceFiles()
+        .filter((sf) => !sf.isDeclarationFile && !program.isSourceFileFromExternalLibrary(sf));
+    return {
+        program,
+        checker: program.getTypeChecker(),
+        options: parsed.options,
+        rootDir: path.dirname(configPath),
+        sourceFiles,
+    };
+}

package/dist/report.js

@@ -0,0 +1,168 @@
+import { stronglyConnectedComponents } from "./graph.js";
+// Layer depth on the condensation of the folder graph: layer 0 depends on
+// nothing; layer N depends only on layers < N. Cyclic groups share a depth.
+function folderLayers(folders) {
+    const sccs = stronglyConnectedComponents(folders.nodes.map((n) => n.id), edgesToAdjacency(folders));
+    const componentOf = new Map();
+    sccs.forEach((scc, i) => scc.forEach((id) => componentOf.set(id, i)));
+    const deps = new Map(sccs.map((_, i) => [i, new Set()]));
+    for (const edge of folders.edges) {
+        const from = componentOf.get(edge.from);
+        const to = componentOf.get(edge.to);
+        if (from !== to)
+            deps.get(from).add(to);
+    }
+    const depth = new Map();
+    const resolve = (component) => {
+        const known = depth.get(component);
+        if (known !== undefined)
+            return known;
+        let d = 0;
+        for (const dep of deps.get(component))
+            d = Math.max(d, resolve(dep) + 1);
+        depth.set(component, d);
+        return d;
+    };
+    const layers = new Map();
+    sccs.forEach((scc, i) => {
+        const d = resolve(i);
+        if (!layers.has(d))
+            layers.set(d, []);
+        layers.get(d).push(...scc);
+    });
+    for (const members of layers.values())
+        members.sort();
+    return layers;
+}
+function edgesToAdjacency(graph) {
+    const adjacency = new Map();
+    for (const edge of graph.edges) {
+        if (!adjacency.has(edge.from))
+            adjacency.set(edge.from, []);
+        adjacency.get(edge.from).push(edge.to);
+    }
+    return adjacency;
+}
+function fanCounts(graph) {
+    const counts = new Map();
+    const entry = (id) => {
+        if (!counts.has(id))
+            counts.set(id, { fanIn: 0, fanOut: 0 });
+        return counts.get(id);
+    };
+    for (const node of graph.nodes)
+        entry(node.id);
+    for (const edge of graph.edges) {
+        entry(edge.from).fanOut++;
+        entry(edge.to).fanIn++;
+    }
+    return counts;
+}
+function cyclesSection(lines, graph, label, cap) {
+    if (graph.cycles.length === 0)
+        return;
+    const shown = cap ? graph.cycles.slice(0, cap) : graph.cycles;
+    lines.push(`### ${label} cycles (${graph.cycles.length})`, "");
+    for (const cycle of shown) {
+        lines.push(`- **Cycle ${cycle.id}** (${cycle.nodes.length} nodes): ${cycle.nodes.join(" ⇄ ")}`);
+        if (graph.level === "file") {
+            const members = new Set(cycle.nodes);
+            for (const edge of graph.edges) {
+                if (members.has(edge.from) && members.has(edge.to) && edge.from !== edge.to) {
+                    lines.push(`  - \`${edge.from}:${edge.line ?? "?"}\` → \`${edge.to}\` (${edge.kind})`);
+                }
+            }
+        }
+    }
+    if (cap && graph.cycles.length > cap) {
+        lines.push(`- … ${graph.cycles.length - cap} more (see JSON output)`);
+    }
+    lines.push("");
+}
+export function renderArchitectureMd(input) {
+    const { folders, files, functions } = input;
+    const lines = [];
+    lines.push("# Architecture Review", "");
+    lines.push(`Project root: \`${folders.root}\``, "");
+    lines.push("| Level | Nodes | Edges | Cycles |");
+    lines.push("|---|---:|---:|---:|");
+    for (const graph of [folders, files, functions]) {
+        lines.push(`| ${graph.level} | ${graph.nodes.length} | ${graph.edges.length} | ${graph.cycles.length} |`);
+    }
+    lines.push("");
+    lines.push("## Folder layering", "");
+    lines.push("Layer 0 depends on nothing; each layer depends only on lower layers.", "Folders in a cycle share a layer.", "");
+    const fans = fanCounts(folders);
+    const fileCount = new Map(folders.nodes.map((n) => [n.id, n.fileCount ?? 0]));
+    lines.push("| Layer | Folder | Files | Fan-in | Fan-out |");
+    lines.push("|---:|---|---:|---:|---:|");
+    const layers = folderLayers(folders);
+    for (const depth of [...layers.keys()].sort((a, b) => a - b)) {
+        for (const folder of layers.get(depth)) {
+            const fan = fans.get(folder);
+            lines.push(`| ${depth} | \`${folder}\` | ${fileCount.get(folder)} | ${fan.fanIn} | ${fan.fanOut} |`);
+        }
+    }
+    lines.push("");
+    const anyCycles = folders.cycles.length + files.cycles.length + functions.cycles.length > 0;
+    lines.push("## Cycles", "");
+    if (anyCycles) {
+        cyclesSection(lines, folders, "Folder");
+        cyclesSection(lines, files, "File");
+        cyclesSection(lines, functions, "Function", 20);
+    }
+    else {
+        lines.push("None found at any level. Your dependency graph is a DAG. 🎉", "");
+    }
+    lines.push("## Notable edges", "");
+    const heaviest = [...folders.edges].sort((a, b) => b.weight - a.weight).slice(0, 10);
+    if (heaviest.length > 0) {
+        lines.push("### Heaviest cross-folder dependencies", "");
+        lines.push("| From | To | Kind | File edges |");
+        lines.push("|---|---|---|---:|");
+        for (const edge of heaviest) {
+            lines.push(`| \`${edge.from}\` | \`${edge.to}\` | ${edge.kind} | ${edge.weight} |`);
+        }
+        lines.push("");
+    }
+    const fileFans = fanCounts(files);
+    const hubs = [...fileFans.entries()]
+        .filter(([, fan]) => fan.fanIn > 0)
+        .sort((a, b) => b[1].fanIn - a[1].fanIn)
+        .slice(0, 10);
+    if (hubs.length > 0) {
+        lines.push("### Most depended-on files (hubs)", "");
+        lines.push("| File | Fan-in | Fan-out |");
+        lines.push("|---|---:|---:|");
+        for (const [id, fan] of hubs) {
+            lines.push(`| \`${id}\` | ${fan.fanIn} | ${fan.fanOut} |`);
+        }
+        lines.push("");
+    }
+    const pairKinds = new Map();
+    for (const edge of folders.edges) {
+        const key = `${edge.from} → ${edge.to}`;
+        if (!pairKinds.has(key))
+            pairKinds.set(key, new Set());
+        pairKinds.get(key).add(edge.kind);
+    }
+    const typeOnlyPairs = [...pairKinds.entries()]
+        .filter(([, kinds]) => kinds.size === 1 && kinds.has("type"))
+        .map(([pair]) => pair)
+        .slice(0, 10);
+    if (typeOnlyPairs.length > 0) {
+        lines.push("### Folder pairs connected only by type imports", "");
+        lines.push("These couplings vanish at runtime — candidates for clean decoupling.", "");
+        for (const pair of typeOnlyPairs)
+            lines.push(`- \`${pair}\``);
+        lines.push("");
+    }
+    if (input.skippedDynamicImports > 0) {
+        lines.push(`> Note: ${input.skippedDynamicImports} dynamic import(s) with non-literal specifiers ` +
+            "could not be resolved and are not in the graph.", "");
+    }
+    lines.push("---", "");
+    lines.push(`Generated by dagward v${input.version}. Machine-readable graphs: ` +
+        "`graph.folders.json`, `graph.files.json`, `graph.functions.json`.");
+    return lines.join("\n") + "\n";
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "dagward",
+  "version": "0.1.0",
+  "description": "Deterministic architecture review for TypeScript projects: dependency graphs at folder, file, and function level.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kanglei1130/dagward.git"
+  },
+  "homepage": "https://github.com/kanglei1130/dagward#readme",
+  "bugs": "https://github.com/kanglei1130/dagward/issues",
+  "keywords": ["architecture", "dependency-graph", "dag", "typescript", "lint", "ai-agents"],
+  "type": "module",
+  "engines": { "node": ">=20" },
+  "bin": { "dagward": "dist/cli.js" },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "typescript": "^5.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "vitest": "^2.0.0"
+  }
+}