depvitals 0.3.0 → 0.4.0

package/schemas/examples/README.md

@@ -0,0 +1,27 @@
+# Report format v1 examples
+
+These six normative examples describe the target v0.4.0 release. Their conceptual root is `/example/project` and their illustrative `tool.version` is `0.4.0`; actual reports use the real selected root and installed tool version. They do not claim that an earlier CLI already accepts format or explanation options. See the [schema](../report-v1.schema.json) and [format description](../README.md).
+
+| Document                                               | Scenario and intended exit                                                                                                                                                                                               |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [scan-clean.json](scan-clean.json)                     | Empty manifest and no supported source; scan exit 0.                                                                                                                                                                     |
+| [scan-findings.json](scan-findings.json)               | Dependencies declare `unused`, devDependencies declare `unused-tool`; `src/index.ts` contains `import item from 'missing';` and a final LF. Scan exit 1. The quote is at zero-based UTF-16 offset 17, line 1, column 18. |
+| [explain-missing.json](explain-missing.json)           | Query `missing` in that same project; exit 1, excluding unrelated unused findings.                                                                                                                                       |
+| [explain-excluded.json](explain-excluded.json)         | Dependency `unused`, no sources, exact ignoreDependencies entry `unused`; query exit 0, preserving its underlying unused finding.                                                                                        |
+| [explain-unknown.json](explain-unknown.json)           | Empty project, query `absent`; completed unknown record and exit 1.                                                                                                                                                      |
+| [explain-node-preload.json](explain-node-preload.json) | Dev dependency `preload` used by the selected Node preload recognition described below; query exit 0.                                                                                                                    |
+
+The Node-preload example assumes this manifest and an empty `entry.cjs`:
+
+```json
+{
+  "devDependencies": { "preload": "1" },
+  "scripts": {
+    "check/node~": "unlisted-tool && node --import=preload/esm --import=preload/esm ./entry.cjs"
+  }
+}
+```
+
+The candidate ordinals are unlisted-tool=0, node=1, preload=2 and preload=3 before declaration filtering. The undeclared commands create no package records or missing findings. The two preload selectors retain distinct script occurrences and the escaped pointer `/scripts/check~1node~0`. Their module selector is `preload/esm`, owned by package `preload`, without installed resolution or execution. This example describes the target recognition; serializing supplied facts alone does not establish that a particular CLI version collects them.
+
+Invalid manifest/config/source inputs intentionally have no report fixture. Their expected stdout is empty, stderr identifies the error and exit is 1. They must not be represented as successful clean documents.

package/schemas/examples/explain-excluded.json

@@ -0,0 +1,53 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "depvitals",
+    "version": "0.4.0"
+  },
+  "mode": "explain",
+  "project": {
+    "root": "/example/project"
+  },
+  "scope": {
+    "sourceExtensions": [".cjs", ".cts", ".js", ".jsx", ".mjs", ".mts", ".ts", ".tsx"],
+    "excludedDirectories": [
+      ".cache",
+      ".git",
+      ".next",
+      ".nuxt",
+      ".turbo",
+      "build",
+      "coverage",
+      "dist",
+      "node_modules",
+      "out"
+    ],
+    "ignorePaths": [],
+    "ignoreDependencies": ["unused"]
+  },
+  "findings": {
+    "unusedDependencies": [],
+    "unusedDevDependencies": [],
+    "missingDependencies": []
+  },
+  "counts": {
+    "unusedDependencies": 0,
+    "unusedDevDependencies": 0,
+    "missingDependencies": 0
+  },
+  "packages": [
+    {
+      "name": "unused",
+      "status": "excluded",
+      "declaredIn": ["dependencies"],
+      "excluded": true,
+      "underlyingFindings": ["unusedDependencies"],
+      "findings": [],
+      "evidence": []
+    }
+  ],
+  "query": {
+    "packageName": "unused",
+    "known": true
+  }
+}

package/schemas/examples/explain-missing.json

@@ -0,0 +1,65 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "depvitals",
+    "version": "0.4.0"
+  },
+  "mode": "explain",
+  "project": {
+    "root": "/example/project"
+  },
+  "scope": {
+    "sourceExtensions": [".cjs", ".cts", ".js", ".jsx", ".mjs", ".mts", ".ts", ".tsx"],
+    "excludedDirectories": [
+      ".cache",
+      ".git",
+      ".next",
+      ".nuxt",
+      ".turbo",
+      "build",
+      "coverage",
+      "dist",
+      "node_modules",
+      "out"
+    ],
+    "ignorePaths": [],
+    "ignoreDependencies": []
+  },
+  "findings": {
+    "unusedDependencies": [],
+    "unusedDevDependencies": [],
+    "missingDependencies": ["missing"]
+  },
+  "counts": {
+    "unusedDependencies": 0,
+    "unusedDevDependencies": 0,
+    "missingDependencies": 1
+  },
+  "packages": [
+    {
+      "name": "missing",
+      "status": "missing",
+      "declaredIn": [],
+      "excluded": false,
+      "underlyingFindings": ["missingDependencies"],
+      "findings": ["missingDependencies"],
+      "evidence": [
+        {
+          "kind": "source",
+          "file": "src/index.ts",
+          "reference": "import",
+          "specifier": "missing",
+          "position": {
+            "offset": 17,
+            "line": 1,
+            "column": 18
+          }
+        }
+      ]
+    }
+  ],
+  "query": {
+    "packageName": "missing",
+    "known": true
+  }
+}

package/schemas/examples/explain-node-preload.json

@@ -0,0 +1,70 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "depvitals",
+    "version": "0.4.0"
+  },
+  "mode": "explain",
+  "project": {
+    "root": "/example/project"
+  },
+  "scope": {
+    "sourceExtensions": [".cjs", ".cts", ".js", ".jsx", ".mjs", ".mts", ".ts", ".tsx"],
+    "excludedDirectories": [
+      ".cache",
+      ".git",
+      ".next",
+      ".nuxt",
+      ".turbo",
+      "build",
+      "coverage",
+      "dist",
+      "node_modules",
+      "out"
+    ],
+    "ignorePaths": [],
+    "ignoreDependencies": []
+  },
+  "findings": {
+    "unusedDependencies": [],
+    "unusedDevDependencies": [],
+    "missingDependencies": []
+  },
+  "counts": {
+    "unusedDependencies": 0,
+    "unusedDevDependencies": 0,
+    "missingDependencies": 0
+  },
+  "packages": [
+    {
+      "name": "preload",
+      "status": "used",
+      "declaredIn": ["devDependencies"],
+      "excluded": false,
+      "underlyingFindings": [],
+      "findings": [],
+      "evidence": [
+        {
+          "kind": "script",
+          "file": "package.json",
+          "pointer": "/scripts/check~1node~0",
+          "command": "preload/esm",
+          "via": "node-preload",
+          "occurrence": 2
+        },
+        {
+          "kind": "script",
+          "file": "package.json",
+          "pointer": "/scripts/check~1node~0",
+          "command": "preload/esm",
+          "via": "node-preload",
+          "occurrence": 3
+        }
+      ]
+    }
+  ],
+  "query": {
+    "packageName": "preload",
+    "known": true
+  }
+}

package/schemas/examples/explain-unknown.json

@@ -0,0 +1,53 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "depvitals",
+    "version": "0.4.0"
+  },
+  "mode": "explain",
+  "project": {
+    "root": "/example/project"
+  },
+  "scope": {
+    "sourceExtensions": [".cjs", ".cts", ".js", ".jsx", ".mjs", ".mts", ".ts", ".tsx"],
+    "excludedDirectories": [
+      ".cache",
+      ".git",
+      ".next",
+      ".nuxt",
+      ".turbo",
+      "build",
+      "coverage",
+      "dist",
+      "node_modules",
+      "out"
+    ],
+    "ignorePaths": [],
+    "ignoreDependencies": []
+  },
+  "findings": {
+    "unusedDependencies": [],
+    "unusedDevDependencies": [],
+    "missingDependencies": []
+  },
+  "counts": {
+    "unusedDependencies": 0,
+    "unusedDevDependencies": 0,
+    "missingDependencies": 0
+  },
+  "packages": [
+    {
+      "name": "absent",
+      "status": "unknown",
+      "declaredIn": [],
+      "excluded": false,
+      "underlyingFindings": [],
+      "findings": [],
+      "evidence": []
+    }
+  ],
+  "query": {
+    "packageName": "absent",
+    "known": false
+  }
+}

package/schemas/examples/scan-clean.json

@@ -0,0 +1,40 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "depvitals",
+    "version": "0.4.0"
+  },
+  "mode": "scan",
+  "project": {
+    "root": "/example/project"
+  },
+  "scope": {
+    "sourceExtensions": [".cjs", ".cts", ".js", ".jsx", ".mjs", ".mts", ".ts", ".tsx"],
+    "excludedDirectories": [
+      ".cache",
+      ".git",
+      ".next",
+      ".nuxt",
+      ".turbo",
+      "build",
+      "coverage",
+      "dist",
+      "node_modules",
+      "out"
+    ],
+    "ignorePaths": [],
+    "ignoreDependencies": []
+  },
+  "findings": {
+    "unusedDependencies": [],
+    "unusedDevDependencies": [],
+    "missingDependencies": []
+  },
+  "counts": {
+    "unusedDependencies": 0,
+    "unusedDevDependencies": 0,
+    "missingDependencies": 0
+  },
+  "packages": [],
+  "query": null
+}

package/schemas/examples/scan-findings.json

@@ -0,0 +1,80 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "depvitals",
+    "version": "0.4.0"
+  },
+  "mode": "scan",
+  "project": {
+    "root": "/example/project"
+  },
+  "scope": {
+    "sourceExtensions": [".cjs", ".cts", ".js", ".jsx", ".mjs", ".mts", ".ts", ".tsx"],
+    "excludedDirectories": [
+      ".cache",
+      ".git",
+      ".next",
+      ".nuxt",
+      ".turbo",
+      "build",
+      "coverage",
+      "dist",
+      "node_modules",
+      "out"
+    ],
+    "ignorePaths": [],
+    "ignoreDependencies": []
+  },
+  "findings": {
+    "unusedDependencies": ["unused"],
+    "unusedDevDependencies": ["unused-tool"],
+    "missingDependencies": ["missing"]
+  },
+  "counts": {
+    "unusedDependencies": 1,
+    "unusedDevDependencies": 1,
+    "missingDependencies": 1
+  },
+  "packages": [
+    {
+      "name": "missing",
+      "status": "missing",
+      "declaredIn": [],
+      "excluded": false,
+      "underlyingFindings": ["missingDependencies"],
+      "findings": ["missingDependencies"],
+      "evidence": [
+        {
+          "kind": "source",
+          "file": "src/index.ts",
+          "reference": "import",
+          "specifier": "missing",
+          "position": {
+            "offset": 17,
+            "line": 1,
+            "column": 18
+          }
+        }
+      ]
+    },
+    {
+      "name": "unused",
+      "status": "unused",
+      "declaredIn": ["dependencies"],
+      "excluded": false,
+      "underlyingFindings": ["unusedDependencies"],
+      "findings": ["unusedDependencies"],
+      "evidence": []
+    },
+    {
+      "name": "unused-tool",
+      "status": "unused",
+      "declaredIn": ["devDependencies"],
+      "excluded": false,
+      "underlyingFindings": ["unusedDevDependencies"],
+      "findings": ["unusedDevDependencies"],
+      "evidence": []
+    }
+  ],
+  "query": null
+}