development · Command reference
qzx diagnoseProject
What it does
Inspects project technologies, dependencies, validation workflows, Git state, source quality, and large files without executing project scripts
Command maturity: Alpha
Available for real use and feedback while its interface and behavior can still evolve. This is the current development-checkout assessment. Every future immutable release tag preserves the exact assessment shipped by that version. Available in PyPI 0.2.2.0.7a5. This page documents the 0.2.2.0.7a5 alpha development checkout.
Behavior and built-in protections
Inspects without changing state
Direct execution for this operation
Uses a native tool when needed
Works without network access
No elevation required by design
Performs bounded static inspection and read-only Git queries. It never executes project-owned tests, linters, type checkers, builds, package scripts, hooks, installers, or migrations; discovered validation commands remain explicitly unverified.
This safety classification was reviewed by OpenAI Codex agent against implementation digest sha256:f78f9567543d98638cbe33e1e7d184f7fa0fbd669d2352fd9609bb2b4bbcd391 on 2026-08-08.
Exact syntax
qzx diagnoseProject [path] --jsonParameters
Swipe or use the horizontal scrollbar to see every column.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| path | str | No | "." | Path to the project directory to diagnose (default: '.') |
Input examples
qzx diagnoseProjectDiagnose the current project without running its scripts
qzx diagnoseProject C:/my/projectDiagnose the project at the specified path
For the complete structured payload, add --json: qzx diagnoseProject [path] --json
Observed output example
Captured with QZX 0.2.2.0.7a5 on Windows 11; exit code 0. Host-dependent values and duration can vary.
Example command: qzx diagnoseProject ../artifacts/qzx-evidence/project-doctor --json
{
"success": true,
"message": "Project diagnosis completed with 1 observed issue. 2 configured validation workflows were discovered but not executed; run the suggested commands before treating the project as release-ready.",
"details": {
"path": "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\project-doctor",
"technologies": [
"Python"
],
"dependencies": {
"manifest_count": 1,
"manifests_found": [
"pyproject.toml"
],
"total_declaration_count": 1,
"unique_declared_package_count": 1,
"unique_packages": [
"httpx"
],
"parse_errors": [],
"manifests": [
{
"path": "pyproject.toml",
"ecosystem": "python",
"status": "parsed",
"declaration_count": 1,
"group_counts": {
"runtime": 1
},
"packages": [
"httpx"
]
}
],
"counting_note": "Declaration totals include repeated packages across manifests and dependency groups; unique_declared_package_count deduplicates normalized package names."
},
"environment": {
"local_files": [],
"template_files": [],
"local_configuration_present": false,
"template_present": false,
"values_inspected": false,
"note": "Only environment filenames are reported; diagnoseProject never reads or returns environment values."
},
"validation": {
"execution_policy": "discovery_only",
"execution_note": "diagnoseProject never executes project-owned tests, linters, type checkers, builds, package scripts, hooks, or installers.",
"tests": {
"configured": true,
"status": "configured_not_run",
"tools": [
"pytest"
],
"configs": [
"tests",
"pyproject.toml [tool.pytest]"
],
"commands": [
"python -m pytest"
]
},
"lint": {
"configured": true,
"status": "configured_not_run",
"tools": [
"ruff"
],
"configs": [
"pyproject.toml [tool.ruff]"
],
"commands": [
"python -m ruff check ."
]
},
"type_checking": {
"configured": false,
"status": "not_configured",
"tools": [],
"configs": [],
"commands": []
},
"build": {
"configured": false,
"status": "not_configured",
"tools": [],
"configs": [],
"commands": []
}
},
"version_control": {
"status": "not_repository",
"reason": "Git did not identify a repository for this path."
},
"source_analysis": {
"unused_code": {
"status": "passed",
"candidate_symbols_count": 0,
"candidate_symbols": [],
"interpretation": "Candidates have no statically visible references; review dynamic uses before removal."
},
"circular_imports": {
"status": "passed",
"cycles_count": 0,
"cycles": []
}
},
"file_scan": {
"scanned_file_count": 3,
"maximum_file_count": 5000,
"scan_complete": true,
"error_count": 0,
"large_file_threshold_bytes": 1048576,
"large_file_threshold_formatted": "1.00 MB",
"large_file_count": 0,
"large_files": []
},
"summary": {
"status": "review",
"issue_count": 1,
"informational_count": 0,
"issue_counts_by_severity": {
"high": 0,
"medium": 0,
"low": 1,
"info": 0
},
"issues": [
{
"code": "git_not_detected",
"severity": "low",
"title": "Git repository not detected",
"description": "The inspected path is not inside a Git working tree.",
"remediation": "Use version control for maintained source projects or confirm that this directory is intentionally unversioned."
}
],
"verification": {
"level": "partial",
"release_readiness": "not_assessed",
"verified_areas": [
"technology and manifest discovery",
"dependency declaration inventory",
"Git working-tree state when Git is available",
"static unused-code candidates",
"static circular-import analysis",
"bounded large-file scan"
],
"configured_but_not_run": [
"tests",
"lint"
],
"suggested_commands": [
"python -m pytest",
"python -m ruff check ."
],
"reason": "The command performs read-only inspection and never executes project-owned validation or build scripts."
}
}
},
"meta": {
"command": "diagnoseProject",
"command_maturity": {
"stage": "alpha",
"label": "Alpha",
"sequence": 2,
"public_executable": true,
"stability": "interface_may_change",
"summary": "Available for real use and feedback while its interface and behavior can still evolve.",
"promotion_review_required": false,
"assessment_scope": "development_checkout"
},
"duration_ms": 452.399,
"schema_version": 1
}
}View the JSON result contract
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"success",
"message",
"meta"
],
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"meta": {
"type": "object",
"required": [
"command",
"command_maturity",
"duration_ms",
"schema_version"
],
"properties": {
"command": {
"type": "string"
},
"command_maturity": {
"type": "object",
"required": [
"stage",
"label",
"sequence",
"public_executable",
"stability",
"summary",
"promotion_review_required",
"assessment_scope"
],
"properties": {
"stage": {
"type": "string"
},
"label": {
"type": "string"
},
"sequence": {
"type": "integer"
},
"public_executable": {
"type": "boolean"
},
"stability": {
"type": "string"
},
"summary": {
"type": "string"
},
"promotion_review_required": {
"type": "boolean"
},
"assessment_scope": {
"type": "string"
},
"note": {
"type": "string"
},
"review": {
"type": "object",
"required": [
"reviewed_on",
"rationale",
"evidence"
],
"properties": {
"reviewed_on": {
"type": "string",
"format": "date"
},
"rationale": {
"type": "string"
},
"evidence": {
"type": "array",
"minItems": 1,
"items": {
"type": "string"
}
},
"replacement": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"duration_ms": {
"type": "number"
},
"schema_version": {
"type": "integer"
}
},
"additionalProperties": true
},
"details": {
"type": "object",
"properties": {
"path": [],
"technologies": [],
"dependencies": [],
"environment": [],
"validation": [],
"version_control": [],
"source_analysis": [],
"file_scan": [],
"summary": []
},
"additionalProperties": true
},
"error": {
"type": "string"
}
},
"additionalProperties": true
}Errors and limits
The public contract requires success=false and a descriptive message on failure. This catalog does not yet declare a command-specific error taxonomy; inspect the result and do not invent error codes.
QZX is alpha software. Optional dependencies, permissions, and host capabilities can change the result.
{
"success": false,
"error": "Path '../artifacts/qzx-evidence/missing-golden-core-path' does not exist.",
"message": "Cannot diagnose the project because '../artifacts/qzx-evidence/missing-golden-core-path' does not exist.",
"meta": {
"command": "diagnoseProject",
"command_maturity": {
"stage": "alpha",
"label": "Alpha",
"sequence": 2,
"public_executable": true,
"stability": "interface_may_change",
"summary": "Available for real use and feedback while its interface and behavior can still evolve.",
"promotion_review_required": false,
"assessment_scope": "development_checkout"
},
"duration_ms": 4.511,
"schema_version": 1
}
}Captured command: qzx diagnoseProject ../artifacts/qzx-evidence/missing-golden-core-path --json
Evidence workflow: captured and digest-validated.
Evidence and provenance
- Implementation
- src/qzx/commands/development/diagnose_project.py
- Documentation channel
- Development documentation 0.2.2.0.7a5 · main · sha256:f2555cf1c06a4bb51aacdb4c3cfb8a4dcdaa991d21751f203e889bd3653fcd24
- Availability
- 0.2.2.0.7a5 or earlier
Keep exploring
Related commands
These commands also belong to the development category. Compare them to choose the operation that best fits your task.
qzx deployProjectPreviews or deploys one explicit artifact over SSH using a verified remote backup, SHA-256 validation, atomic promotion, health checks, and automatic rollbackqzx findUnusedCodeFinds functions, classes, and exports with no statically visible references so they can be reviewed for removalqzx compareFilesCompares text files line by line and binary files by exact bytes and SHA-256qzx formatCodeFormats source code files by auto-detecting language and invoking the right formatter