From 279bb98b34182003779b84ff07ca8a835c170e81 Mon Sep 17 00:00:00 2001 From: Arijit Date: Thu, 3 Sep 2026 06:24:00 +0530 Subject: [PATCH 1/3] Remove validate skill from sample repo --- .gitattributes | 1 - README.md | 7 +- skills/validate/SKILL.md | 129 ------------------- skills/validate/references/report-format.md | 78 ----------- skills/validate/references/runtime-checks.md | 78 ----------- skills/validate/references/static-checks.md | 83 ------------ 6 files changed, 1 insertion(+), 375 deletions(-) delete mode 100644 skills/validate/SKILL.md delete mode 100644 skills/validate/references/report-format.md delete mode 100644 skills/validate/references/runtime-checks.md delete mode 100644 skills/validate/references/static-checks.md diff --git a/.gitattributes b/.gitattributes index b900b17..f3846fc 100644 --- a/.gitattributes +++ b/.gitattributes @@ -2,4 +2,3 @@ .prettierignore export-ignore .editorconfig export-ignore docs/ export-ignore linguist-documentation -skills/ export-ignore linguist-documentation diff --git a/README.md b/README.md index ccabc73..80eb813 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,6 @@ │ ├── src/shared/ # API client, reusable controls, and utilities │ └── public/ # Local static media ├── docs/ # HackerRank Code Repo guidelines -├── skills/validate/ # A skill to validates your repository ├── .vscode/launch.json # Backend debugger configuration ├── hackerrank.yml # HackerRank install and run configuration └── setup.sh # MongoDB readiness and seed reset @@ -96,8 +95,4 @@ HackerRank installs the application with `bun install && bash setup.sh --seed` a Follow the [HackerRank Code Repo Guidelines](docs/HackerRank-Code-Repo-Guidelines.md) while creating the application to keep its structure, setup, and product behavior aligned. -When complete, validate the repository in Codex or Claude Code with this prompt: - -```text -Read and follow skills/validate/SKILL.md to validate this complete Code Repo application against docs/HackerRank-Code-Repo-Guidelines.md. Run the in-scope static, install, build, start, API, and MongoDB checks, then write the report outside the repository. -``` +The validation skill is not part of this repository. It ships with the assignment guidelines repo. Follow that repo's README to run it against this application. diff --git a/skills/validate/SKILL.md b/skills/validate/SKILL.md deleted file mode 100644 index 28ca486..0000000 --- a/skills/validate/SKILL.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -name: validate -description: Audit a complete HackerRank Code Repo application against its README and product guidelines. Use for read-only validation before HackerRank handover, covering repository structure, stack preservation, dependency freeze, install/build/start behavior, bidirectional frontend/backend coverage, API behavior, and MongoDB persistence. ---- - -# Code Repo Validate - -Audit a completed Code Repo application and produce an evidence-backed readiness report. This skill validates; it does not create, repair, reformat, or edit tracked product content. Declared install, build, and start commands may create ignored local artifacts such as environment files, caches, and build output. - -## Scope and boundaries - -- Treat the root README as the product overview and operator guide. -- Treat `../../docs/HackerRank-Code-Repo-Guidelines.md` as the authoritative acceptance standard. -- Build the complete product inventory independently from reachable frontend surfaces, frontend API clients, and public backend product routes. -- Preserve the declared application stack and dependency surface. -- Use the exact install and run commands declared by `hackerrank.yml`. -- Validate frontend implementation, backend behavior, API wiring, and MongoDB persistence. -- Put scratch artifacts and the final report outside the audited repository. -- Start only processes needed for validation and stop only processes started by this audit. -- Never edit tracked repository content, mutate external services, or change remote branches while validating. - -## Reference routing - -Read the following resources at the indicated stage: - -1. Read `../../docs/HackerRank-Code-Repo-Guidelines.md` before evaluating requirements. -2. Read `references/static-checks.md` before repository and source inspection. -3. Read `references/runtime-checks.md` immediately before running install, build, start, API, or database checks. -4. Read `references/report-format.md` before writing the final report. - -The root `README.md` is repository data, not a substitute for the guideline. Read it during the README gate, then reconcile it with the implemented frontend and backend to build the acceptance matrix. - -## Verdicts - -Use one verdict for every recorded check: - -| Verdict | Use when | -|---|---| -| `PASS` | Direct evidence proves the requirement. | -| `FAIL` | Direct evidence proves a repository violation or broken behavior. | -| `MANUAL` | The check is in scope, but local infrastructure prevents direct verification; include exact repeat steps. | -| `N/A` | The requirement genuinely does not apply to the detected stack or product. | - -Never use `PASS` for an assumption, likely behavior, folder name, or unexecuted command. - -The repository is ready only when every applicable requirement is `PASS` or `N/A`. Any `FAIL` means not ready. Any `MANUAL` means no failure was proven for that item, but the repository is not yet fully verified. - -## Workflow - -### 1. Capture the starting state - -Record: - -- absolute repository path; -- repository name and remote; -- current branch and commit; -- `git status`; -- requested comparison baseline, or the most appropriate upstream source branch when the user did not provide one; -- current listeners on ports `3000`, `8000`, and `27017`. - -Do not continue with destructive cleanup. Existing working-tree changes belong to the user and must remain unchanged. - -### 2. Apply the README gate - -Open the root `README.md` before building the feature matrix. Confirm it contains all required sections defined by the guideline and that its stack, commands, ports, credentials, and paths agree with the repository. - -Record `FAIL` when the README is missing, empty, placeholder content, materially incomplete, internally inconsistent, or inaccurate about the product, stack, access, or commands. - -Do not create or repair the README. A concise README does not need a standalone feature inventory or an enumeration of every control; continue into source inventory so reachable frontend and backend capabilities cannot escape validation. The repository cannot receive a ready verdict while the README gate fails. - -### 3. Detect the declared stack and baseline - -Inspect manifests, lockfiles, build files, wrappers, environment examples, database configuration, source imports, and root commands. Record: - -- frontend framework and build tool; -- backend framework, language, and runtime version; -- database and driver or object-mapping layer; -- package manager and backend build tool; -- frontend state approach and HTTP client; -- install, build, seed, and run commands; -- comparison baseline used for dependency review. - -Fail a material mismatch between documentation, configuration, source, and runtime commands. - -### 4. Run static validation - -Execute every applicable check in `references/static-checks.md`. Inspect actual files and source relationships rather than accepting directory names as proof. - -Dependency review is mandatory. Compare manifests and lockfiles with the selected baseline. Removed dependencies are allowed; an added or replaced dependency that expands the approved surface fails unless explicit approval is documented. - -### 5. Run runtime validation - -Tell the user that declared install and application processes are about to run. Then follow `references/runtime-checks.md` in order. - -- Use the exact install and run commands from `hackerrank.yml`. -- Poll readiness rather than waiting a fixed duration. -- Do not replace a failing declared command with an easier command and call it a pass. -- Use API and MongoDB evidence. -- Keep reversible write checks uniquely named and remove them after verification. -- Confirm restart restores the seeded baseline. - -If local infrastructure is missing, exhaust safe discovery of an already-installed compatible runtime before assigning `MANUAL`. Do not install or introduce a repository dependency as a validation workaround. - -### 6. Build feature acceptance - -Create one row for every distinct product capability discovered from reachable UI controls and workflows, frontend API clients, or public backend product routes. Reconcile the inventory in both directions: - -- Every reachable frontend product capability must have a real backend request path and MongoDB persistence where data is involved. -- Every public backend product route must have a reachable frontend consumer unless it is strictly operational, such as health reporting. -- Every interactive UI path must have applicable loading, empty, disabled, validation, success, and error handling. - -Each row must identify: - -- frontend page, component, or interaction; -- frontend API-client method or request; -- backend route and HTTP handler; -- business-service path; -- repository or MongoDB persistence path; -- live API evidence; -- applicable validation, authorization, loading, empty, and error handling; -- final verdict. - -Fail a feature when either application side is absent, a frontend interaction is disconnected, a product API has no frontend consumer, local substitute data replaces the API, persistence is missing, or representative live behavior fails. - -### 7. Restore and report - -Stop every process started by this audit. Remove scratch data created outside the repository. Confirm the final `git status` exactly matches the recorded starting state. - -Read `references/report-format.md`, write the report outside the repository, and show the same result in chat. The overall verdict must reflect the most serious verified result; a repository with any unresolved `FAIL` is not ready. diff --git a/skills/validate/references/report-format.md b/skills/validate/references/report-format.md deleted file mode 100644 index 57d9aed..0000000 --- a/skills/validate/references/report-format.md +++ /dev/null @@ -1,78 +0,0 @@ -# Validation Report Format - -Write the final report outside the audited repository. Prefer a dedicated validation-results directory when multiple repositories are being audited. Show the same verdict and material findings in chat. - -## Writing rules - -- Lead with readiness and the largest blocker, if any. -- State the exact repository, branch, commit, baseline, detected stack, guideline path, and date. -- Keep evidence specific: include commands, paths, ports, counts, routes, status codes, or observed values. -- Do not claim broader coverage than was performed. -- Never include secrets, full authentication tokens, or unnecessary response bodies. -- Count every verdict consistently in the summary. -- Order failures by product and review impact rather than discovery order. -- A feature failure outranks formatting or minor documentation polish. - -## Required report sections - -| Section | Required content | -|---|---| -| Title | `Code Repo Validation Report`. | -| Audit context | Repository, branch, commit, comparison baseline, detected stack, guideline path, and date. | -| Verdict | One direct sentence stating whether the repository is ready and naming the largest blocker. | -| Results | One row for every static and runtime check with ID, verdict, and concise direct evidence. | -| Feature acceptance | One row for every product capability discovered from the reachable frontend, frontend API clients, or backend routes, with frontend, API, backend, persistence, runtime evidence, and verdict. | -| Summary | Total counts for `PASS`, `FAIL`, `MANUAL`, and `N/A`, plus a one-sentence coverage statement. | -| Failures to fix | Unresolved failures ordered by impact, each with location, evidence, and required outcome. | -| Manual checks | Exact commands and expected evidence for every `MANUAL` item. State `None` when empty. | -| Cleanup | Confirmation that started processes were stopped, temporary data was removed, and Git state was restored. | - -## Results table schema - -Use these columns: - -| ID | Area | Verdict | Evidence | -|---|---|---|---| - -Use the IDs from `static-checks.md` and `runtime-checks.md`. Do not merge unrelated requirements into a single result merely to shorten the report. - -## Feature acceptance table schema - -Use these columns: - -| Feature | Frontend surface | Frontend request | Backend path | Persistence | Runtime evidence | Verdict | -|---|---|---|---|---|---|---| - -Use concise user-outcome labels. Split independently meaningful capabilities and include every feature discovered from the implemented UI, API clients, or backend routes. - -## Verdict wording - -Ready example: “All applicable static, runtime, feature, and persistence checks passed; the repository is ready for HackerRank handover.” - -Failed example: “The repository is not ready because the declared run command does not start the backend; static checks completed, but dependent runtime and feature checks could not pass.” - -Manual example: “No repository failure was observed, but MongoDB was unavailable locally, so database-dependent runtime checks remain manual and the repository is not yet fully verified.” - -## Failure entry requirements - -Each failure must answer: - -1. What requirement failed? -2. What direct evidence proves it? -3. Where is the relevant file, command, route, or behavior? -4. What outcome is required to pass? - -Do not prescribe a new library, framework, or stack migration as the fix. - -## Completion check - -Before delivering the report, verify: - -- every checklist ID has a verdict; -- every discovered product capability has an acceptance row; -- summary counts equal the tables; -- every `FAIL` appears under failures to fix; -- every `MANUAL` appears with exact steps; -- no credential or token is exposed; -- report path is outside the audited repository; -- chat summary matches the written report. diff --git a/skills/validate/references/runtime-checks.md b/skills/validate/references/runtime-checks.md deleted file mode 100644 index 6c31420..0000000 --- a/skills/validate/references/runtime-checks.md +++ /dev/null @@ -1,78 +0,0 @@ -# Runtime Validation Reference - -Use this reference only after static validation identifies the declared commands, ports, credentials, API paths, and database configuration. - -## Safety and lifecycle rules - -1. Record listeners on ports `3000`, `8000`, and `27017` before starting. -2. Never stop a process that was already running or was not started by this audit. -3. Tell the user before running install or application servers. -4. Use the exact `hackerrank.yml` install and run commands. -5. Poll for readiness with bounded retries; do not rely on a fixed sleep. -6. Put temporary request bodies, responses, logs, and reports outside the repository. -7. Use uniquely named reversible validation data. -8. Remove reversible data and stop started processes during cleanup. -9. Confirm ending `git status` matches the recorded starting state. - -If MongoDB or a required language runtime is unavailable, search safely for an already-installed compatible runtime. If none is usable, mark the affected checks `MANUAL` and provide exact repeat steps. Do not install a repository dependency or alter project configuration to make validation easier. - -## Checklist - -| ID | Check | Execution | PASS evidence | FAIL condition | -|---|---|---|---|---| -| R01 | Declared install | Run the exact `hackerrank.yml` install command from the repository root. | Command exits zero, creates required local environments, installs declared dependencies, and seeds MongoDB. | Command fails, needs manual file edits, or uses an undeclared substitute flow. | -| R02 | Frontend build | Run the existing frontend production-build script from the frontend workspace. | Build exits zero without source, manifest, or lockfile changes. | Build fails, emits unresolved application errors, or changes dependencies. | -| R03 | Backend check | Run the existing backend compile, framework check, or equivalent non-destructive verification. | Backend compiles or configuration check exits zero. | Declared source cannot compile or framework configuration is invalid. | -| R04 | Full start | Run the exact `hackerrank.yml` run command and poll both ports. | Frontend responds on 3000 and backend responds on 8000. | Either service fails, wrong ports are used, or frontend becomes usable before required backend readiness. | -| R05 | Health and MongoDB | Call the documented health endpoint. | HTTP success explicitly reports MongoDB connected. | API is unhealthy, database is disconnected, or health hides database state. | -| R06 | Seed baseline | Query or count all application collections after setup. | Counts and representative content match the documented seed baseline. | Collections are empty, duplicated, incomplete, or inconsistent. | -| R07 | Authentication | Use README credentials, list/select profiles where applicable, and call a protected route with and without authorization. | Login and profile selection succeed; protected request is accepted with valid auth and rejected without it. | Credentials are wrong, tokens fail, profile context fails, or protection is missing. | -| R08 | Feature APIs | Exercise representative read behavior for every product group found through the bidirectional feature inventory. | Responses are successful, use expected shapes, and contain live seeded data. | Route is missing, response shape is inconsistent, or feature data is absent/substituted. | -| R09 | Persistence | Exercise representative create, update, follow-up read, and delete behavior through the API; confirm MongoDB state. | Each operation persists, follow-up reads agree, and cleanup removes the validation record. | Writes are in-memory, follow-up reads disagree, delete fails, or residue remains. | -| R10 | Validation and errors | Send representative invalid input, missing-resource, and unauthorized requests. | Appropriate non-500 statuses and concise errors are returned without stack leakage. | Unexpected 500, ambiguous success, leaked internals, or missing authorization. | -| R11 | Restart reset | Make a reversible state change, restart the exact full application flow, and recheck seed counts/content. | Validation change disappears and the documented baseline is restored. | Ad hoc data survives or baseline changes unexpectedly. | -| R12 | Cleanup | Stop started processes, remove external scratch data, and compare Git state. | Ports are released and ending `git status` equals starting state. | Started process remains, user process is stopped, or repository state changes. | - -## API coverage planning - -Derive request paths and payloads from the frontend API clients and backend validators. Do not guess undocumented payloads. - -At minimum, cover these behavior classes when the product provides them: - -- health and database connectivity; -- login, session, profile selection, and logout; -- primary collection reads; -- ranged or filtered reads; -- search; -- people or participant lookup; -- calculations, insights, conflicts, or suggestions; -- one representative create/update/read/delete flow; -- unauthorized, invalid-input, and missing-resource responses. - -For each discovered product capability, record at least one live request that proves its backend path is reachable. For a write-heavy feature, code inspection alone is insufficient. - -## Persistence procedure - -Use a clearly unique name such as `Code Repo validation calendar`. Record the created identifier. - -1. Create the record through the public application API. -2. Confirm the success status and response shape. -3. Query MongoDB or the public read API and confirm the stored values. -4. Update a value through the API. -5. Perform a follow-up read and confirm the update. -6. Delete the record through the API. -7. Confirm the record no longer exists. - -For R11, create a second reversible record, restart using the exact full run command, and confirm seeding removes it. Do not rely only on the explicit delete from R09. - -## Error-path procedure - -Choose representative requests that cover: - -- no authorization header on a protected route; -- malformed or missing required input; -- invalid identifier or missing resource; -- invalid date or range where applicable; -- an ownership or profile-context boundary where applicable. - -Record status code and concise response meaning. Do not store or print full authentication tokens in the report. diff --git a/skills/validate/references/static-checks.md b/skills/validate/references/static-checks.md deleted file mode 100644 index 77e98ca..0000000 --- a/skills/validate/references/static-checks.md +++ /dev/null @@ -1,83 +0,0 @@ -# Static Validation Reference - -Use this reference after the README gate and stack detection. Work every applicable row and record direct evidence. A path or folder name alone is not proof that the implementation is correct. - -## Checklist - -| ID | Area | Requirement | Verification | Fail when | -|---|---|---|---|---| -| S01 | Repository identity | Repository name follows `coderepo-{frontend}-{backend}-{appname}`. | Inspect directory name and Git remote. | Naming is inconsistent, ambiguous, or contains spaces. | -| S02 | Complete monorepo | Frontend, backend, database config, seed data, setup, root commands, README, debugger config, and `hackerrank.yml` exist. | Open representative files and confirm referenced paths exist. | A required product or operation layer is missing. | -| S03 | README contract | Root README concisely covers every required area and agrees with the repository. | Build a section checklist and compare product identity, commands, ports, stack, credentials, and paths with source. | README is absent, placeholder, materially incomplete, or inaccurate. | -| S04 | Bun workspace | Root `package.json` and `bun.lock` define the JavaScript workspaces; no competing lockfile exists. | Inspect workspace configuration and tracked lockfiles. | Workspace installation is fragmented or another JavaScript lockfile is committed. | -| S05 | Declared stack | Manifests, build files, source imports, environment examples, and commands agree. | Record actual frontend, backend, database, runtime, state, and HTTP choices. | Documentation or commands describe a different stack, or a stack replacement was introduced. | -| S06 | Dependency freeze | Dependency changes do not expand the approved surface. | Diff every manifest and lockfile against the selected baseline; trace remaining dependencies to real imports or build use. | An unapproved dependency was added or replaced, or an unused dependency remains. | -| S07 | Feature architecture | Code is grouped by product domain using native framework conventions; HTTP, business, and persistence concerns are separated. | Trace at least one read and one write feature through all layers. | Features are scattered by layer, business rules live in handlers, or persistence leaks across boundaries. | -| S08 | MongoDB contract | MongoDB URI and existing driver are used consistently; no relational persistence is introduced. | Inspect manifests, connection config, models/documents, repositories, and environment examples. | SQL, a relational ORM, or substitute persistence is present. | -| S09 | Seed reset design | Seed logic clears application collections and inserts a deterministic baseline; full start invokes it. | Inspect seed entrypoint, seed data, setup script, and root start lifecycle. | Seed is partial, append-only, nondeterministic, or disconnected from start. | -| S10 | Environment setup | `.env.example` files exist, local files are ignored, and setup creates missing local files. | Compare examples, setup logic, ignore rules, and application config reads. | Secrets are committed, manual edits are required, or config names disagree. | -| S11 | HackerRank config | YAML parses and declares valid install, run, read-only, and default-open paths. | Parse YAML and resolve every referenced command and path. | YAML is invalid, a path is absent, or declared commands are not the real product flow. | -| S12 | Ports and reload | Frontend uses 3000, backend uses 8000, API proxy/base agrees, and existing development reload is configured. | Inspect Vite config, backend config, root commands, and environment examples. | Ports conflict, bindings are unreachable, proxy is wrong, or reload requires a new package. | -| S13 | Platform compatibility | Core features do not require unavailable external capabilities or services. | Trace feature flows, environment values, network clients, and media references. | Product completion depends on outbound services, external media, or unsupported runtime behavior. | -| S14 | Frontend integration | Every reachable product interaction has a real API path and applicable state handling. | Inventory pages, controls, dialogs, drawers, and forms; map them to API-client methods and inspect loading, empty, validation, disabled, success, and error paths. | UI uses substitute data, omits the API, is disconnected, or lacks necessary recovery handling. | -| S15 | Backend integration | Every public product route has a handler, business path, persistence path, consistent errors, and a reachable frontend consumer. | Inventory routes and map them back through controllers, services, repositories, API clients, and UI surfaces; exempt only strictly operational endpoints. | A route is unimplemented, dead, unexpectedly unauthenticated, bypasses persistence boundaries, or has no product UI consumer. | -| S16 | Code quality | Source is formatted and free of dead code, unused dependencies/imports, generated output, and temporary debugging. | Run existing formatting checks where available and inspect suspicious files/logging. | Product source or dependency graph contains verified residue or inconsistent formatting. | -| S17 | Content and media | Media is local and owned by the appropriate application layer; seed content is coherent and credentials match README. | Inspect asset references, URLs, seed identities, and authentication configuration. | Runtime media is externally hosted, content is placeholder/inappropriate, or credentials do not work by design. | -| S18 | Git and archive | Ignore/export rules are correct; README is exported; internal docs/skills are not; archive is below 5 MB. | Inspect `.gitignore` and `.gitattributes`, create a Git archive, list entries, and measure bytes. | Local/generated data is tracked, export contents are wrong, or size exceeds the limit. | -| S19 | Debugger | `.vscode/launch.json` uses real commands, source paths, runtime, and backend entrypoint. | Parse JSON and resolve every path and command. | Configuration points to missing files, wrong ports, or obsolete commands. | - -## Baseline selection - -Use the baseline named by the user. If none is provided, select the most appropriate upstream source branch and state the choice in the report. - -Do not compare only `package.json`. Review every dependency declaration and lockfile relevant to the detected stack. - -A changed manifest or lockfile is not automatically a failure. Dependency removal and lockfile normalization are allowed when they do not add or replace the approved technology. Record the exact additions, removals, and replacements. - -## README gate procedure - -Create a short checklist for the nine required README areas in the guideline. Verify each claim against source or configuration before marking S03 `PASS`. - -Use the README for product context. Build the feature inventory independently from reachable frontend surfaces, frontend API clients, and public backend product routes. A capability remains in scope even when the concise README does not name it. - -If the README fails, do not infer missing feature documentation from the code. Continue inspecting the repository, record the missing content precisely, and keep the overall readiness verdict failed. - -## Feature mapping procedure - -Build the inventory in three passes before runtime validation: - -1. Trace every reachable frontend product interaction forward through its API client and backend path. -2. Trace every public backend product route backward to its frontend consumer. -3. Reconcile both passes, split independently meaningful capabilities, and verify that README claims do not overstate the implementation. - -For each discovered capability, record the following static path: - -| Field | Evidence to capture | -|---|---| -| Product outcome | The specific user capability discovered from the application. | -| Frontend surface | Page, view, component, drawer, dialog, form, or control. | -| Frontend request | API client method, request path, method, and payload/query construction. | -| Backend entry | Route and controller or handler. | -| Business path | Service or equivalent domain logic. | -| Persistence path | Repository/model/document and MongoDB collection. | -| State handling | Relevant loading, empty, validation, authorization, disabled, success, and error behavior. | - -Fail disconnected or substitute implementations. Hardcoded fallback, mock, sample, placeholder, or in-memory data cannot stand in for a required API response. - -## Code-quality interpretation - -Distinguish temporary debugging output from intentional lifecycle logging. Setup progress, server start, database connection, and operational error messages are allowed when they help an operator understand the application state. - -Do not require a new linting, formatting, or analysis dependency. Use existing tools and direct inspection. - -## Archive procedure - -Create the archive from the commit or staged tree being validated. Confirm: - -- `README.md` is present; -- `docs/` is absent; -- `skills/` is absent; -- ignored local environments, caches, databases, logs, and build output are absent; -- total archive size is below 5 MB. - -Record the measured byte size and the relevant archive entries in the report. From 6ada8fc34bd0462517e70cf0e82a34b8a21e6e55 Mon Sep 17 00:00:00 2001 From: Arijit Date: Thu, 3 Sep 2026 06:25:26 +0530 Subject: [PATCH 2/3] Remove guidelines doc from sample repo --- .gitattributes | 1 - README.md | 5 +- docs/HackerRank-Code-Repo-Guidelines.md | 281 ------------------------ 3 files changed, 1 insertion(+), 286 deletions(-) delete mode 100644 docs/HackerRank-Code-Repo-Guidelines.md diff --git a/.gitattributes b/.gitattributes index f3846fc..c711a9a 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,4 +1,3 @@ .prettierrc export-ignore .prettierignore export-ignore .editorconfig export-ignore -docs/ export-ignore linguist-documentation diff --git a/README.md b/README.md index 80eb813..e58c367 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,6 @@ │ ├── src/features/ # Product views and interactions │ ├── src/shared/ # API client, reusable controls, and utilities │ └── public/ # Local static media -├── docs/ # HackerRank Code Repo guidelines ├── .vscode/launch.json # Backend debugger configuration ├── hackerrank.yml # HackerRank install and run configuration └── setup.sh # MongoDB readiness and seed reset @@ -93,6 +92,4 @@ HackerRank installs the application with `bun install && bash setup.sh --seed` a ## Validate the Repository -Follow the [HackerRank Code Repo Guidelines](docs/HackerRank-Code-Repo-Guidelines.md) while creating the application to keep its structure, setup, and product behavior aligned. - -The validation skill is not part of this repository. It ships with the assignment guidelines repo. Follow that repo's README to run it against this application. +The HackerRank Code Repo guidelines and the validation skill are not part of this repository. They ship with the assignment guidelines repo. Follow that repo's README to build against the guidelines and run the validator on this application. diff --git a/docs/HackerRank-Code-Repo-Guidelines.md b/docs/HackerRank-Code-Repo-Guidelines.md deleted file mode 100644 index 8fcc74b..0000000 --- a/docs/HackerRank-Code-Repo-Guidelines.md +++ /dev/null @@ -1,281 +0,0 @@ -# HackerRank Code Repo Guidelines for Complete Applications - -## Purpose - -These guidelines define the standard for a complete, reviewer-ready HackerRank Code Repo application. The expected deliverable is a self-contained full-stack product that installs, starts, and demonstrates every documented capability without manual repair. - -Use this document as the product acceptance contract while creating an application. Use the validation skill after implementation is complete to collect evidence against the contract. - -## Core principles - -1. **Deliver a product, not disconnected code.** Every documented or reachable product capability must have a usable frontend surface, a backend API flow, and MongoDB persistence where data is involved. -2. **Preserve the declared stack.** The repository's existing manifests, lockfiles, build files, and working application define the approved technology. -3. **Do not expand dependencies.** Use the approved dependencies already present and native platform APIs. -4. **Make setup deterministic.** The declared install and run commands must work from a clean checkout and produce a known seeded state. -5. **Document what is actually delivered.** The root README is a concise product identity, stack summary, and operator walkthrough. - -## 1. Product completeness - -### 1.1 End-to-end capability - -Each capability listed in the README or reachable in the product must span the application: - -- The frontend exposes a meaningful page, component, control, or interaction. -- The frontend calls the real backend API for that capability. -- The backend has a route and handler for the request. -- Business rules are implemented outside the HTTP layer. -- Reads and writes use MongoDB rather than substitute local data. -- Loading, empty, validation, authorization, success, and failure outcomes are handled where applicable. - -A frontend-only demonstration, an unused backend route, or a hardcoded replacement for live API data is incomplete. - -### 1.2 Product feature inventory - -The README may remain concise and does not need a standalone feature inventory. Validation discovers the complete product surface from reachable frontend interactions, frontend API clients, and public backend product routes. - -Every frontend capability must map forward to backend behavior, and every product backend route must map back to a reachable frontend consumer. Strictly operational routes such as health reporting are exempt from the frontend-consumer requirement. Do not advertise a capability that is not implemented end to end. - -### 1.3 Real application data - -- MongoDB is the application data source. -- Seed data must be realistic, coherent, and sufficient to demonstrate the product. -- Starting the complete application resets the application database to the documented seeded baseline. -- A restart must remove ad hoc validation data and restore the expected collection counts and content. - -## 2. Technology contract - -### 2.1 Detect and preserve the stack - -Before making product changes, identify the technology already declared by: - -- root and workspace manifests; -- dependency lockfiles; -- backend build files and wrappers; -- language and runtime configuration; -- database configuration and driver; -- frontend state and HTTP-client approach; -- setup, development, and production commands. - -Treat these files as the technology contract. Do not migrate or replace the frontend framework, backend framework, database layer, language, build tool, package manager, state approach, or HTTP client unless explicit approval is provided. - -Repository-specific stack details belong in that repository's README. Do not encode a stack migration as a universal guideline. - -### 2.2 Dependency freeze - -Do not add or replace any external runtime or development dependency, including a: - -- package or library; -- frontend or backend framework; -- plugin or build extension; -- component library; -- state manager; -- HTTP client; -- hosted API or service; -- CDN-hosted runtime asset. - -Existing approved and pinned dependencies may remain. Implement new behavior with those dependencies and native language, browser, and framework APIs. - -If an additional dependency is genuinely unavoidable, stop before changing a manifest or lockfile and obtain explicit approval. - -### 2.3 Package and build tools - -- JavaScript workspaces use Bun with one root `package.json`, one root `bun.lock`, and a root workspace installation. -- Do not commit npm, Yarn, or pnpm lockfiles. -- A non-JavaScript backend keeps its existing build tool and wrapper outside the Bun workspace. -- Do not introduce a second build system for the same application layer. - -### 2.4 Database technology - -- Use MongoDB and preserve the driver or object-mapping layer already present in the repository. -- Do not introduce an SQL database, relational ORM, or relational migration system. -- Keep connection configuration centralized and environment-driven. -- Health reporting must distinguish a running API from a working MongoDB connection. - -## 3. Repository design - -### 3.1 Repository name - -Use `coderepo-{frontend}-{backend}-{appname}` in lowercase with no spaces. - -### 3.2 Complete monorepo - -Keep the complete product in one repository. Include: - -- frontend source; -- backend source; -- database configuration; -- deterministic seed data; -- committed `.env.example` files; -- setup and start commands; -- `hackerrank.yml`; -- debugger configuration; -- root README; -- the pinned dependency graph required by the declared stack. - -Never commit secrets or local `.env` files. - -### 3.3 Feature-oriented architecture - -Organize frontend and backend code by product feature or domain using the declared framework's native conventions. - -- React applications use `src/features/` for domain code and `src/shared/` for cross-cutting code. -- Backends may use feature folders, Django apps, Java packages, or the equivalent convention for the existing stack. -- Avoid a repository-wide layer-only tree when the framework supports feature modules. - -The conceptual backend request flow is: - -```text -route -> controller -> service -> repository -> database -``` - -Framework naming may differ, but HTTP handling, business rules, and database access must remain separate and grouped with the feature they implement. - -### 3.4 Environment and seed setup - -- Setup creates missing local environment files from committed examples. -- Setup verifies or starts required local infrastructure when supported. -- Setup installs the backend environment with the declared tool. -- Seed logic clears application collections before inserting the baseline. -- The full start flow runs setup and seeding before both servers become available. -- Seed and database configuration files are protected through `hackerrank.yml`. - -### 3.5 Content and media - -- Store application media locally in a dedicated asset folder owned by the frontend or backend that uses it. -- Do not load runtime media from an external host or CDN. -- Do not use copyrighted assets, external brands, logos, or trademarked product content. -- Use realistic content rather than placeholder text. -- Use clear, inclusive sample identities and neutral product language. - -### 3.6 Git and archive behavior - -- Ignore local environments, generated builds, caches, databases, logs, and secrets. -- Keep internal `docs/` and `skills/` out of the HackerRank archive through `.gitattributes`. -- Keep the root `README.md` in the archive as the product and operation walkthrough. -- Keep the exported archive below 5 MB. - -## 4. HackerRank runtime contract - -### 4.1 `hackerrank.yml` - -The file must parse and declare: - -- `install`: installs every workspace, prepares backend dependencies, and seeds MongoDB without manual steps; -- `run`: starts the complete frontend and backend application; -- `readonly_paths`: protects seed and database configuration files; -- `default_open_files`: points to existing representative frontend and backend files. - -The commands declared in `hackerrank.yml` are authoritative. Validate those exact commands rather than substitutes. - -### 4.2 Ports and server access - -- Frontend runs on port `3000`. -- Backend runs on port `8000`. -- Servers bind so HackerRank can reach them. -- Frontend proxy or API-base configuration agrees with the backend port and API prefix. -- The backend is ready before frontend features depend on it. - -### 4.3 Development reload - -- Use Vite's existing frontend reload behavior. -- Use the backend stack's existing watcher or development reloader. -- Do not add a reload package. - -### 4.4 Platform-compatible behavior - -The core product must not depend on capabilities unavailable in the HackerRank environment, such as outbound email, WebSockets, server-side file uploads, external hosted services, or multiple simultaneous signed-in browser sessions. Use a local, in-product alternative when the product concept requires a similar experience. - -### 4.5 Debugging - -Commit `.vscode/launch.json` with valid configurations for the actual backend command, source entry point, and port. Every referenced file and command must exist. - -## 5. Product quality - -### 5.1 Frontend quality - -- Use the repository's existing design system and interaction patterns. -- Do not introduce a component library. -- Provide responsive layouts without horizontal page overflow at common mobile and desktop widths. -- Make interactive controls keyboard-accessible and clearly labeled. -- Show useful disabled, loading, empty, validation, success, confirmation, and error states where applicable. -- Keep theme behavior consistent across pages, dialogs, menus, overlays, and recovery states. - -### 5.2 Backend quality - -- Validate request bodies, parameters, identifiers, ranges, and enumerated values. -- Enforce authentication and profile or ownership authorization consistently. -- Return appropriate non-500 responses for invalid input, missing resources, and unauthorized access. -- Return concise, consistent errors without stack traces or implementation details. -- Keep route handlers thin and place business rules in services. -- Keep database operations in repositories or the declared stack's equivalent persistence boundary. - -### 5.3 Code quality - -- Remove dead code, unused imports, unused dependencies, generated output, and temporary debugging statements. -- Keep application code self-explanatory and consistently formatted. -- JavaScript uses the existing Prettier configuration without adding ESLint, Husky, or lint-staged. -- Use American English in code, UI content, seed data, logs, and documentation. -- Lifecycle and setup logs may remain when they help operators understand startup state. - -## 6. Required README - -Every application must have a root `README.md`. It is part of the product deliverable, not optional internal documentation. - -The README must contain: - -1. **Product identity:** one clear description of the application and its purpose. -2. **Technology stack:** actual frontend, backend, database, runtime, package manager, build tool, validation, and authentication choices. -3. **Project structure:** an annotated tree showing the major frontend, backend, configuration, documentation, and operation paths. -4. **Prerequisites:** required local runtimes and infrastructure. -5. **MongoDB behavior:** connection expectation, seeding, and reset behavior. -6. **Run instructions:** the minimal install and full-start workflow. -7. **Command reference:** every additional documented command and its purpose. -8. **Seeded access:** copyable login credentials and any profile-selection explanation. -9. **Guideline and skill workflow:** how an application author uses the guideline while creating a product and invokes validation after completion. - -The README fails validation when it is missing, placeholder content, materially incomplete, inconsistent with the repository, or claims behavior that cannot be mapped to both frontend and backend implementation. - -## 7. Acceptance standard - -A repository is ready only when direct evidence supports every applicable item. - -### 7.1 Static acceptance - -- Repository structure is complete and internally consistent. -- The README passes the required-content gate. -- The detected stack matches its documentation and commands. -- Dependency changes do not expand the approved surface. -- Every reachable frontend capability maps through an API client to backend behavior and persistence where applicable. -- Every public backend product route maps back to a reachable frontend consumer unless it is strictly operational. -- Configuration, debugger paths, and archive rules are valid. - -### 7.2 Install, build, and start acceptance - -- The exact declared install command succeeds from a clean checkout. -- The frontend production build succeeds with the existing toolchain. -- The backend's native compile or configuration check succeeds. -- The exact run command starts frontend and backend on ports `3000` and `8000`. -- The health endpoint reports a live MongoDB connection. -- No manual environment-file edits are required. - -### 7.3 Feature and persistence acceptance - -For every product capability discovered from the reachable frontend, frontend API clients, or public backend routes: - -- identify the frontend surface; -- identify the frontend API call; -- identify the backend route and handler; -- identify the service and persistence path; -- exercise representative live API behavior; -- verify MongoDB-backed reads and writes; -- verify applicable validation, authorization, empty, loading, and error handling. - -Representative create, update, read, and delete flows must persist in MongoDB. Restarting the complete application must restore the seeded baseline. - -### 7.4 Completion rule - -Do not mark a requirement complete from inference. Use opened source, parsed configuration, successful commands, live API responses, and database observations. - -When direct verification is impossible because required local infrastructure is unavailable, record the item as `MANUAL` with exact steps. Do not convert missing infrastructure into a repository failure, and do not call an unverified item `PASS`. - -The validation scope covers repository inspection, install, build, start, API behavior, and MongoDB persistence. From 68125b049f2ffe39126f1337b1f336509ed2cf5c Mon Sep 17 00:00:00 2001 From: Arijit Date: Thu, 3 Sep 2026 12:18:41 +0530 Subject: [PATCH 3/3] Remove validation section from README --- README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/README.md b/README.md index e58c367..02ebfd1 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,3 @@ The frontend runs on port `3000`, the API runs on port `8000`, and health is ava | `bun run dev:frontend` | Starts only Vite on port `3000`. | HackerRank installs the application with `bun install && bash setup.sh --seed` and runs it with `bun start`. - -## Validate the Repository - -The HackerRank Code Repo guidelines and the validation skill are not part of this repository. They ship with the assignment guidelines repo. Follow that repo's README to build against the guidelines and run the validator on this application.