auditor-lambda 0.3.12 → 0.3.14

package/docs/release.md

@@ -0,0 +1,131 @@
+# Release
+
+## Release gate
+
+Run from the repository root:
+
+```bash
+npm ci
+npm run verify:release
+```
+
+`verify:release` covers:
+
+- TypeScript typecheck
+- full automated test suite
+- linked-install `audit-code` smoke coverage
+- packaged-install `audit-code` smoke coverage
+- tarball contract verification for shipped assets and runtime entrypoints
+- packaged and linked verification of bootstrap install behavior
+
+For live child-process output while debugging smoke tests:
+
+```bash
+AUDIT_CODE_VERBOSE=1 npm run smoke:packaged-audit-code
+AUDIT_CODE_VERBOSE=1 npm run smoke:linked-audit-code
+```
+
+The packaged smoke path strips inherited `npm_config_*`, `NODE_AUTH_TOKEN`, and
+`NPM_TOKEN` values before nested npm operations so dry runs and smoke installs
+do not accidentally inherit publish credentials or suppress tarball generation.
+
+## Publication
+
+Publication is operational through GitHub Actions Trusted Publishing.
+
+Workflow:
+
+```text
+.github/workflows/publish-package.yml
+```
+
+The workflow:
+
+- requests `id-token: write` for npm OIDC exchange
+- pins Node `22.14.0`
+- upgrades npm to `>=11.5.1`
+- runs `npm run verify:release`
+- previews the packed tarball with `npm pack --dry-run`
+- publishes with public access and provenance
+- defaults semver prerelease versions to the `next` dist-tag unless overridden
+- verifies that the published version resolves from the registry
+- uploads `*-npm-logs` artifacts on failure
+
+Routine CI exercises Node `20` and Node `22`.
+
+## Version bump helpers
+
+Use:
+
+```bash
+npm run release:patch
+```
+
+That bumps the version, updates `package.json` and `package-lock.json`, and
+creates the release commit and annotated tag.
+
+Available variants:
+
+- `npm run release:minor`
+- `npm run release:major`
+
+Full maintainer flow:
+
+```bash
+npm run release:patch:publish
+```
+
+That command checks the worktree, runs the release gate, bumps the version,
+commits, tags, pushes `main` and the tag, creates the GitHub Release, waits for
+`publish-package.yml`, and confirms the new npm version resolves.
+
+Minor and major publish variants:
+
+- `npm run release:minor:publish`
+- `npm run release:major:publish`
+
+## Manual workflow dispatch
+
+Use GitHub Actions `workflow_dispatch` to exercise or run the publish workflow.
+
+Dry run:
+
+- `dry_run=true`
+- `publish_tag=auto`
+
+Live publish:
+
+- `dry_run=false`
+- `publish_tag=auto` unless intentionally overriding the dist-tag
+
+`publish_tag=auto` resolves stable versions to `latest` and prerelease versions
+to `next`.
+
+Publishing a GitHub Release triggers the same workflow.
+
+## Trusted publisher setup
+
+npm Trusted Publishing is configured for this repository. If repository,
+workflow, or ownership details change, keep the npm trusted publisher entry
+aligned with:
+
+- owner or organization: `OhOkThisIsFine`
+- repository: `auditor-lambda`
+- workflow filename: `publish-package.yml`
+
+## Troubleshooting
+
+If a GitHub Actions run fails:
+
+1. download the uploaded `*-npm-logs` artifact
+2. rerun `npm ci` and `npm run verify:release` locally from the same commit
+3. for publish failures, rerun `publish-package.yml` with `dry_run=true`
+4. confirm npm Trusted Publishing still targets `publish-package.yml`
+
+Post-publish checks:
+
+```bash
+npm view auditor-lambda version
+npm view auditor-lambda dist-tags --json
+npm audit signatures
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditor-lambda",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",

package/schemas/audit_plan_metrics.schema.json

@@ -0,0 +1,347 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "audit_plan_metrics.schema.json",
+  "title": "Audit Plan Metrics",
+  "type": "object",
+  "required": [
+    "generated_at",
+    "task_count",
+    "packet_count",
+    "estimated_agent_reduction",
+    "estimated_agent_reduction_ratio",
+    "unique_file_count",
+    "task_file_reference_count",
+    "repeated_file_reference_count",
+    "total_task_lines",
+    "total_packet_lines",
+    "repeated_line_reference_count",
+    "min_task_lines",
+    "max_task_lines",
+    "average_task_lines",
+    "lens_task_counts",
+    "priority_task_counts",
+    "packet_quality",
+    "packet_size"
+  ],
+  "properties": {
+    "generated_at": { "type": "string" },
+    "task_count": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "packet_count": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "estimated_agent_reduction": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "estimated_agent_reduction_ratio": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "unique_file_count": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "task_file_reference_count": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "repeated_file_reference_count": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "total_task_lines": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "total_packet_lines": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "repeated_line_reference_count": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "min_task_lines": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "max_task_lines": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "average_task_lines": {
+      "type": "number",
+      "minimum": 0
+    },
+    "largest_task_id": { "type": "string" },
+    "largest_packet_id": { "type": "string" },
+    "lens_task_counts": {
+      "$ref": "#/$defs/lensCounts"
+    },
+    "priority_task_counts": {
+      "type": "object",
+      "required": ["high", "medium", "low"],
+      "properties": {
+        "high": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "medium": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "low": {
+          "type": "integer",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
+    },
+    "packet_quality": {
+      "type": "object",
+      "required": [
+        "average_cohesion_score",
+        "boundary_crossing_count",
+        "merge_edge_kind_counts",
+        "boundary_edge_kind_counts",
+        "orphan_task_count",
+        "high_fan_in_file_count",
+        "high_fan_out_file_count",
+        "weakly_explained_gap_counts",
+        "weakly_explained_file_extension_counts",
+        "weakly_explained_packet_count",
+        "weakly_explained_packet_ids",
+        "weakly_explained_packet_samples",
+        "largest_unexplained_packet_files"
+      ],
+      "properties": {
+        "average_cohesion_score": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "boundary_crossing_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "merge_edge_kind_counts": {
+          "$ref": "#/$defs/edgeKindCounts"
+        },
+        "boundary_edge_kind_counts": {
+          "$ref": "#/$defs/edgeKindCounts"
+        },
+        "orphan_task_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "high_fan_in_file_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "high_fan_out_file_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "weakly_explained_gap_counts": {
+          "$ref": "#/$defs/weaklyExplainedGapCounts"
+        },
+        "weakly_explained_file_extension_counts": {
+          "$ref": "#/$defs/countRecord"
+        },
+        "weakly_explained_packet_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "weakly_explained_packet_ids": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "weakly_explained_packet_samples": {
+          "type": "array",
+          "maxItems": 12,
+          "items": { "$ref": "#/$defs/weaklyExplainedPacketSample" }
+        },
+        "largest_unexplained_packet_id": { "type": "string" },
+        "largest_unexplained_packet_files": {
+          "type": "integer",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
+    },
+    "packet_size": {
+      "type": "object",
+      "required": [
+        "single_task_packets",
+        "multi_task_packets",
+        "max_tasks_per_packet",
+        "max_files_per_packet"
+      ],
+      "properties": {
+        "single_task_packets": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "multi_task_packets": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "max_tasks_per_packet": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "max_files_per_packet": {
+          "type": "integer",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "countRecord": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "integer",
+        "minimum": 0
+      }
+    },
+    "edgeKindCounts": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "integer",
+        "minimum": 0
+      }
+    },
+    "weaklyExplainedPacketSample": {
+      "type": "object",
+      "required": [
+        "packet_id",
+        "primary_gap",
+        "file_count",
+        "sample_file_paths",
+        "cohesion_score",
+        "internal_edge_count",
+        "boundary_edge_count",
+        "unexplained_file_count"
+      ],
+      "properties": {
+        "packet_id": { "type": "string" },
+        "primary_gap": {
+          "type": "string",
+          "enum": [
+            "missing_internal_edges",
+            "unexplained_files",
+            "partial_cohesion"
+          ]
+        },
+        "file_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "sample_file_paths": {
+          "type": "array",
+          "maxItems": 8,
+          "items": { "type": "string" }
+        },
+        "cohesion_score": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "internal_edge_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "boundary_edge_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "unexplained_file_count": {
+          "type": "integer",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
+    },
+    "weaklyExplainedGapCounts": {
+      "type": "object",
+      "required": [
+        "missing_internal_edges",
+        "unexplained_files",
+        "partial_cohesion"
+      ],
+      "properties": {
+        "missing_internal_edges": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "unexplained_files": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "partial_cohesion": {
+          "type": "integer",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
+    },
+    "lensCounts": {
+      "type": "object",
+      "properties": {
+        "correctness": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "architecture": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "maintainability": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "security": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "reliability": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "performance": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "data_integrity": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "tests": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "operability": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "config_deployment": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "observability": {
+          "type": "integer",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/external_analyzer_results.schema.json

@@ -7,6 +7,41 @@
   "properties": {
     "tool": { "type": "string" },
     "generated_at": { "type": "string" },
+    "ownership_roots": {
+      "type": "array",
+      "description": "Optional analyzer-supplied ownership roots. Each root says a bounded set of checked-in paths belongs to the same module or package root and is translated into graph reference edges.",
+      "items": {
+        "type": "object",
+        "required": ["root", "paths"],
+        "properties": {
+          "root": {
+            "type": "string",
+            "description": "Repository-relative ownership root directory."
+          },
+          "paths": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string" },
+            "description": "Repository-relative files known to belong to this root."
+          },
+          "kind": {
+            "type": "string",
+            "description": "Optional analyzer-specific ownership kind, such as 'python-package' or 'module'."
+          },
+          "confidence": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "description": "Analyzer confidence for the ownership hint."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Short explanation of why the analyzer emitted this root."
+          }
+        },
+        "additionalProperties": false
+      }
+    },
     "results": {
       "type": "array",
       "items": {

package/schemas/graph_bundle.schema.json

@@ -18,7 +18,22 @@
               "to": { "type": "string" },
               "kind": {
                 "type": "string",
-                "description": "Import edge kind from the graph extractor (e.g. 'esm', 'commonjs', 'dynamic', 're-export')."
+                "description": "Import edge kind from the graph extractor (e.g. 'esm', 'commonjs', 'dynamic', 're-export', 'python-import', 'python-from-import')."
+              },
+              "direction": {
+                "type": "string",
+                "enum": ["directed", "undirected"],
+                "description": "Whether the edge should be interpreted as directional."
+              },
+              "confidence": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1,
+                "description": "Extractor confidence for graph-informed planning."
+              },
+              "reason": {
+                "type": "string",
+                "description": "Short explanation of why the edge exists."
               }
             },
             "additionalProperties": false
@@ -35,6 +50,21 @@
               "kind": {
                 "type": "string",
                 "description": "Call edge kind from the graph extractor (e.g. 'sync', 'async', 'constructor', 'callback')."
+              },
+              "direction": {
+                "type": "string",
+                "enum": ["directed", "undirected"],
+                "description": "Whether the edge should be interpreted as directional."
+              },
+              "confidence": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1,
+                "description": "Extractor confidence for graph-informed planning."
+              },
+              "reason": {
+                "type": "string",
+                "description": "Short explanation of why the edge exists."
               }
             },
             "additionalProperties": false
@@ -50,7 +80,22 @@
               "to": { "type": "string" },
               "kind": {
                 "type": "string",
-                "description": "Reference edge kind from literal or path-oriented extraction (e.g. 'relative-string-reference', 'repo-path-reference')."
+                "description": "Reference edge kind from literal or path-oriented extraction (e.g. 'relative-string-reference', 'repo-path-reference', 'test-source-link', 'workspace-package-link' from package or workspace manifests, 'typescript-project-reference-link' from TypeScript project references, 'go-workspace-module-link' from Go workspace use directives, 'cargo-workspace-member-link' from Cargo workspace members, 'maven-module-link' from Maven reactor modules, 'analyzer-ownership-root-link' from external analyzer ownership hints)."
+              },
+              "direction": {
+                "type": "string",
+                "enum": ["directed", "undirected"],
+                "description": "Whether the edge should be interpreted as directional."
+              },
+              "confidence": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1,
+                "description": "Extractor confidence for graph-informed planning."
+              },
+              "reason": {
+                "type": "string",
+                "description": "Short explanation of why the edge exists."
               }
             },
             "additionalProperties": false