dsh-model-everything 0.1.0 → 0.3.0

package/src/structure-tool.ts

@@ -2,9 +2,11 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from './json-value.js'
 import { REPORT_SCHEMAS } from './engine.js'
 import { reviewStructure } from './structure.js'
+import { scanDependencyGraph } from './scan.js'
 import { reviewGranularity, type GranularityDiagram } from './granularity.js'
 import { OptionShapeError, optionRefusal, requireArrayOption } from './option-shape.js'
 import { renderReportText } from './report-view.js'
+import { reportCard, reportResultView } from './presentation.js'
 
 export const STRUCTURE_TOOL_NAME = 'uml_structure_verify'
 
@@ -19,7 +21,7 @@ export const STRUCTURE_TOOL_NAME = 'uml_structure_verify'
 export const umlStructureTool = defineTool({
   name: STRUCTURE_TOOL_NAME,
   description:
-    'Audit a structure diagram as a dependency graph. Takes PlantUML component, package, class or deployment text, or a Mermaid class diagram. Reports UML020 isolated node, UML021 dangling reference, UML022 cycle (shortest path), UML023 disallowed edge and UML024 layer violation against a matrix, UML025 missing required edge, and UML026 when no node is declared. The matrix is {rules: [{id, source, allow?, deny?, require?}], layers: [{name, members}], default: "allow"|"deny"}. Ids and members accept globs (`*`, `?`). Deny beats allow, and layers run top-first, so downward edges pass and upward ones are UML024. With a matrix, every edge appears in `edgeVerdicts` with the rules it matched. Pass `diagrams` instead of `diagram` to check several levels at once: each child must refine its parent. This audits the diagram, not the code: reconcile it with a source-side scan. Read `verdict`, not `ok`. For state or activity diagrams use `uml` and `model_verify`.',
+    'Audit a structure diagram as a dependency graph. Takes PlantUML component, package, class or deployment text, or a Mermaid class diagram - or `repoPath`, a source tree, in which case it builds the graph from the import constructs the source itself uses and no drawing is needed. Reports UML020 isolated node, UML021 dangling reference, UML022 cycle (shortest path), UML023 disallowed edge and UML024 layer violation against a matrix, UML025 missing required edge, and UML026 when no node is declared. The matrix is {rules: [{id, source, allow?, deny?, require?}], layers: [{name, members}], default: "allow"|"deny"}. Ids and members accept globs (`*`, `?`). Deny beats allow, and layers run top-first, so downward edges pass and upward ones are UML024. With a matrix, every edge appears in `edgeVerdicts` with the rules it matched. Pass `diagrams` instead of `diagram` to check several levels at once: each child must refine its parent. It answers **what the graph is**: which edges exist, which node has no edge, which cycle, and whether an edge breaks a matrix you supplied. It does not judge whether the design meant to allow those edges - `model_design_review` does that against the rules the design declares for itself. When the question is whether an import exists from one layer to another, this answers it, from the code. Read `verdict`, not `ok`. For state or activity diagrams use `uml` and `model_verify`.',
   parameters: {
     diagram: {
       type: 'string',
@@ -34,6 +36,10 @@ export const umlStructureTool = defineTool({
       enum: ['auto', 'plantuml', 'mermaid'],
       description: 'Diagram language. Default auto (detected from the text).',
     },
+    repoPath: {
+      type: 'string',
+      description: 'Directory or single source file to scan instead of drawing the diagram yourself. Reads the import construct of C/C++, Python, TypeScript/JavaScript, Go, Rust, Java/Kotlin/Scala, C#, PHP, Ruby, Lua, Zig, Dart and Elixir, building a file graph for file languages and a package graph for package languages (Go, Java, C#). The graph is reviewed by the same checks; `diagram` and `diagrams` are then ignored.',
+    },
     matrix: {
       type: 'json',
       description: 'Optional dependency matrix: {rules: [{id, source, allow?, deny?, require?}], layers: [{name, members}], default: "allow"|"deny"}. Every edge is judged against it and the matched rule ids are reported.',
@@ -52,7 +58,12 @@ export const umlStructureTool = defineTool({
     render(args, value) {
       return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
     },
+    // The card a UI shows, separated from the text the model reads.
+    presentationMeta(_args, value) {
+      return reportCard(value, STRUCTURE_TOOL_NAME) as unknown as JsonValue
+    },
   },
+  presentResult: reportResultView(STRUCTURE_TOOL_NAME),
   timeoutMs: 10_000,
   isConcurrencySafe: () => true,
   async execute(args) {
@@ -81,6 +92,27 @@ export const umlStructureTool = defineTool({
         return optionRefusal(error, 'STRUCTURE_OPTION_INVALID') as unknown as JsonValue
       }
     }
+    if (args.repoPath !== undefined) {
+      try {
+        const scanned = scanDependencyGraph(args.repoPath)
+        // A source module is a declared node that depends on others: not a container, and it has a
+        // line only when it came from a drawing, so the field stays absent.
+        const graph = {
+          notation: 'plantuml' as const,
+          nodes: scanned.nodes.map((id) => ({ id, label: id, kind: 'component' as const, container: false, declared: true })),
+          edges: scanned.edges.map((edge) => ({ from: edge.from, to: edge.to, line: 0 })),
+          warnings: [],
+        }
+        return reviewStructure({
+          diagram: '',
+          graph,
+          scan: { files: scanned.filesRead, unresolved: scanned.unresolved.length, packages: scanned.packages.length, languages: scanned.languages.map((entry) => entry.language) },
+          ...(args.matrix === undefined ? {} : { matrix: args.matrix }),
+        }) as unknown as JsonValue
+      } catch (error) {
+        return optionRefusal(error, 'STRUCTURE_OPTION_INVALID') as unknown as JsonValue
+      }
+    }
     if (args.diagram === undefined) {
       return { ok: false, ran: false, verdict: 'fail', verdictReason: 'the tool did not run: pass `diagram` (one structure diagram) or `diagrams` (several levels with parents)', schema: REPORT_SCHEMAS.structure, errorCode: 'UML_INPUT', error: 'structure review needs `diagram` or `diagrams`' } as unknown as JsonValue
     }

package/src/structure.ts

@@ -107,6 +107,10 @@ export interface StructureSummary {
   errors: number
   warnings: number
   rules: number
+  /** The most depended-on nodes, by incoming edges. What a reader asks first and counts worst. */
+  hubs: { id: string; dependents: number }[]
+  /** Modules nothing depends on (no outgoing edges), capped for the report. */
+  leaves: string[]
 }
 
 export interface StructureReport {
@@ -503,6 +507,10 @@ export function shortestCycle(nodes: string[], edges: StructureEdge[]): string[]
 export interface StructureReviewOptions {
   /** Diagram text to review. */
   diagram: string
+  /** A graph built from source, instead of parsed from a diagram. `diagram` is then ignored. */
+  graph?: StructureGraph
+  /** How the graph was produced, when it came from a scan rather than a drawing. */
+  scan?: { files: number; unresolved: number; packages: number; languages: string[] }
   notation?: 'auto' | StructureNotation
   /** Dependency matrix: allowed/denied edges, layers, required edges. */
   matrix?: unknown
@@ -531,8 +539,9 @@ function requireDiagramText(value: unknown): string {
 export function reviewStructure(options: StructureReviewOptions): StructureReport {
   // Not `if (options.diagram !== undefined)`: a missing `diagram` reached the parser as `undefined`
   // and threw a read of `split` on it - the same defect, one guard narrower.
-  requireDiagramText(options.diagram)
-  const graph = parseStructure(options.diagram, options.notation ?? 'auto')
+  // A graph built from source arrives already parsed; a caller that passes one has no diagram text to
+  // require, so the text guard belongs to the other branch.
+  const graph = options.graph ?? parseStructure(requireDiagramText(options.diagram), options.notation ?? 'auto')
   const warnings = [...graph.warnings]
   const findings: Finding[] = []
   const nodes = graph.nodes
@@ -730,6 +739,26 @@ export function reviewStructure(options: StructureReviewOptions): StructureRepor
     })
   }
 
+  // Degree is what a reader asks first and counts worst: which module everything depends on, and which
+  // depends on nothing. Counting it here means the answer is one line in the report rather than a scan of
+  // the graph by hand, which is where a correct graph still produced a wrong answer.
+  const inDegree = new Map<string, number>()
+  const outDegree = new Map<string, number>()
+  for (const edge of graph.edges) {
+    inDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1)
+    outDegree.set(edge.from, (outDegree.get(edge.from) ?? 0) + 1)
+  }
+  const hubs = [...inDegree.entries()]
+    .filter(([, count]) => count > 0)
+    .sort((a, b) => (b[1] === a[1] ? a[0].localeCompare(b[0]) : b[1] - a[1]))
+    .slice(0, 5)
+    .map(([id, dependents]) => ({ id, dependents }))
+  const leaves = nodes
+    .filter((node) => !node.container && (outDegree.get(node.id) ?? 0) === 0)
+    .map((node) => node.id)
+    .sort()
+    .slice(0, 10)
+
   const errors = findings.filter((finding) => finding.severity === 'error').length
   const warningCount = findings.filter((finding) => finding.severity === 'warning').length
   const summary: StructureSummary = {
@@ -745,6 +774,8 @@ export function reviewStructure(options: StructureReviewOptions): StructureRepor
     errors,
     warnings: warningCount,
     rules: rules.length,
+    hubs,
+    leaves,
   }
 
   const nextSteps: string[] = []
@@ -761,10 +792,13 @@ export function reviewStructure(options: StructureReviewOptions): StructureRepor
     notation: graph.notation,
     graph,
     ...(options.matrix === undefined ? {} : { edgeVerdicts }),
+    ...(options.scan === undefined ? {} : { scan: options.scan }),
     findings,
     summary,
     hashes: {
-      diagram: createHash('sha256').update(options.diagram).digest('hex'),
+      // A graph built from source has no diagram text to hash; hashing the text would hash the empty
+      // string, and every scan would then carry the same input hash.
+      diagram: createHash('sha256').update(options.graph === undefined ? options.diagram : canonicalJson({ nodes: options.graph.nodes.map((node) => node.id), edges: options.graph.edges.map((edge) => ({ from: edge.from, to: edge.to })) })).digest('hex'),
       ...(options.matrix === undefined ? {} : { matrix: createHash('sha256').update(canonicalJson(options.matrix)).digest('hex') }),
     },
     warnings,

package/src/tool.ts

@@ -2,7 +2,9 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from './json-value.js'
 import { runVerification } from './engine.js'
 import { renderReportText } from './report-view.js'
+import { reportCard, reportResultView } from './presentation.js'
 import { OptionShapeError, optionRefusal, requireObjectOption } from './option-shape.js'
+import { oneOf } from './model-file.js'
 
 export const MODEL_VERIFY_TOOL_NAME = 'model_verify'
 
@@ -22,8 +24,11 @@ export const modelVerifyTool = defineTool({
   parameters: {
     model: {
       type: 'json',
-      required: true,
-      description: 'LogicModelV1 state machine model to verify.',
+      description: 'LogicModelV1 state machine model to verify. Pass this, or modelPath, not both.',
+    },
+    modelPath: {
+      type: 'string',
+      description: 'Path to a JSON file holding the model, instead of inlining it. Formatting does not matter: whitespace, a BOM and pretty printing all parse. Relative paths resolve against the process working directory, which is the session workspace.',
     },
     maxStates: {
       type: 'integer',
@@ -41,6 +46,10 @@ export const modelVerifyTool = defineTool({
       type: 'json',
       description: 'Optional object mapping BEFORE state ids to AFTER state ids. Omit for identity mapping (same state names).',
     },
+    check: {
+      type: 'string',
+      description: 'Print one check in full when the digest truncated it. Pass the check id the CHECKS line lists (for example A9); the per-check budget no longer applies, and an id this report does not carry is answered with the ids that it does.',
+    },
     reportView: {
       type: 'string',
       enum: ['digest', 'full'],
@@ -53,9 +62,14 @@ export const modelVerifyTool = defineTool({
       description: 'this plugin verification report with summary and per-check findings.',
     },
     render(args, value) {
-      return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
+      return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full', check: args.check }) }]
+    },
+    // The card a UI shows, separated from the text the model reads.
+    presentationMeta(_args, value) {
+      return reportCard(value, MODEL_VERIFY_TOOL_NAME) as unknown as JsonValue
     },
   },
+  presentResult: reportResultView(MODEL_VERIFY_TOOL_NAME),
   timeoutMs: 10_000,
   isConcurrencySafe: () => true,
   async execute(args) {
@@ -81,7 +95,8 @@ export const modelVerifyTool = defineTool({
           )
         }
       }
-      return runVerification(args.model, {
+      const model = oneOf(args.model, args.modelPath, 'model', 'modelPath', 'VERIFY_OPTION_INVALID')
+      return runVerification(model, {
         maxStates: args.maxStates,
         maxPermutationEvents: args.maxPermutationEvents,
         beforeModel: args.beforeModel,