@xenos1996/usat 1.0.0

package/rules/core/repo.yaml

@@ -0,0 +1,303 @@
+id: core/repo
+title: Repository & Project Structure
+section: S1
+section_title: Repository & Project Structure
+description: >
+  Root hygiene, the essential-files baseline, and version-control quality.
+  Cheap to fix, expensive to ignore — this is where most leaked credentials
+  and most onboarding pain originate.
+version: '1.0'
+
+rules:
+  - id: REPO-001
+    title: .gitignore is present
+    section: S1
+    section_title: Repository & Project Structure
+    severity: CRITICAL
+    class: security
+    check: { kind: file_exists, files: ['.gitignore'] }
+    why: >
+      Without a .gitignore the next `git add -A` commits node_modules, build
+      output, and — sooner or later — a .env file.
+    remediation: 'Add a .gitignore for your stack (github/gitignore has templates).'
+    references: ['CWE-540', 'OpenSSF-Scorecard:Binary-Artifacts']
+
+  - id: REPO-002
+    title: No environment/secret files committed
+    section: S1
+    section_title: Repository & Project Structure
+    severity: CRITICAL
+    class: security
+    check:
+      kind: tracked_absent
+      patterns:
+        [
+          '.env',
+          '.env.*',
+          '*.env',
+          '*.pem',
+          '*.key',
+          '*.p12',
+          '*.pfx',
+          'id_rsa*',
+          'credentials*',
+          'secrets/**',
+          '.npmrc',
+          '.pypirc',
+        ]
+    why: 'A committed .env is a published credential. Rotating is the only fix.'
+    remediation: 'Remove from the index, rotate every value in the file, purge history (git filter-repo / BFG), add to .gitignore.'
+    references: ['CWE-798', 'ASVS-14.3.2', 'OpenSSF-Scorecard:Binary-Artifacts']
+
+  - id: REPO-003
+    title: No secrets in git history
+    section: S1
+    section_title: Repository & Project Structure
+    severity: CRITICAL
+    class: security
+    check:
+      kind: command
+      run: '! git log -p --all | grep -qiE "(api[_-]?key|secret|password|passwd|token|private[_-]?key)[[:space:]]*[:=][[:space:]]*[A-Za-z0-9/+_-]{16,}"'
+      expect_exit: 0
+    why: 'Deleting a secret from HEAD does not delete it from history. Anyone who cloned the repo still has it.'
+    evidence: 'Command output, or a manual `gitleaks detect --log-opts=--all` run.'
+    remediation: 'Rotate the exposed values and rewrite history with git-filter-repo. Rotation first: assume it is already public.'
+    references: ['CWE-798', 'ASVS-14.3.2']
+
+  - id: REPO-004
+    title: README present
+    section: S1
+    section_title: Repository & Project Structure
+    severity: HIGH
+    class: documentation
+    check:
+      kind: any_file
+      patterns: ['README.md', 'readme.md', 'README.rst', 'README.txt', 'README']
+    why: 'The README is the front door. Without it, every new contributor needs a human guided tour.'
+    remediation: 'Write: what this is, how to install, how to run it, how to contribute. Four headings, one page.'
+    references: ['CII-Best-Practices']
+
+  - id: REPO-005
+    title: LICENSE present
+    section: S1
+    section_title: Repository & Project Structure
+    severity: HIGH
+    class: compliance
+    check:
+      kind: any_file
+      patterns: ['LICENSE*', 'COPYING*']
+    why: 'No license means "all rights reserved" by default. Nobody can legally use it, including you, later.'
+    remediation: 'Add MIT / Apache-2.0 / GPL-3.0 as appropriate. Choose at choosealicense.com.'
+    references: ['OpenSSF-Scorecard:License', 'SPDX']
+
+  - id: REPO-006
+    title: .env.example documents required configuration
+    section: S1
+    section_title: Repository & Project Structure
+    severity: HIGH
+    class: maintainability
+    applies_when:
+      any:
+        - { fact: 'has:database' }
+        - { fact: 'platform:server' }
+        - { fact: 'auth:jwt' }
+        - { fact: 'auth:apikey' }
+        - { fact: 'auth:oauth' }
+    check:
+      kind: any_file
+      patterns: ['.env.example', '.env.sample', '.env.template', 'env.example', 'config.example.*']
+    why: 'Undocumented required env vars turn setup into archaeology.'
+    remediation: 'Add .env.example listing every variable the app reads, with safe placeholder values and a comment per var.'
+    references: ['ASVS-14.3.2']
+
+  - id: REPO-007
+    title: Build artifacts and dependencies are not committed
+    section: S1
+    section_title: Repository & Project Structure
+    severity: HIGH
+    class: maintainability
+    check:
+      kind: tracked_absent
+      patterns:
+        [
+          'dist/**',
+          'build/**',
+          'out/**',
+          'node_modules/**',
+          'target/**',
+          '.venv/**',
+          'venv/**',
+          '*.egg-info/**',
+          '__pycache__/**',
+          'coverage/**',
+          '.next/**',
+        ]
+    why: 'Committed build output bloats the repo, guarantees merge conflicts, and hides the real source in review noise.'
+    remediation: 'Untrack (git rm -r --cached) and add the paths to .gitignore.'
+    references: ['OpenSSF-Scorecard:Binary-Artifacts']
+
+  - id: REPO-008
+    title: Large binaries are not committed directly
+    section: S1
+    section_title: Repository & Project Structure
+    severity: MEDIUM
+    class: maintainability
+    check:
+      kind: tracked_absent
+      patterns:
+        [
+          '*.mp4',
+          '*.mov',
+          '*.zip',
+          '*.tar.gz',
+          '*.tgz',
+          '*.exe',
+          '*.dll',
+          '*.so',
+          '*.dylib',
+          '*.jar',
+          '*.war',
+          '*.psd',
+          '*.sketch',
+        ]
+    why: 'Git stores every revision of every binary forever. Use Git LFS or object storage.'
+    remediation: 'Move binaries to LFS or object storage; rewrite history if the repo has already grown past ~200 MB.'
+    references: ['OpenSSF-Scorecard:Binary-Artifacts']
+
+  - id: REPO-009
+    title: SECURITY.md published
+    section: S1
+    section_title: Repository & Project Structure
+    severity: HIGH
+    class: security
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check:
+      kind: any_file
+      patterns: ['SECURITY.md', '.github/SECURITY.md', 'docs/SECURITY.md']
+    why: 'Without a disclosure route, researchers either stay silent or post publicly. Neither helps you.'
+    remediation: 'Add SECURITY.md with supported versions and a report address. GitHub surfaces it in the Security tab.'
+    references: ['OpenSSF-Scorecard:Security-Policy', 'NIST-SSDF-RV.1.1']
+
+  - id: REPO-010
+    title: CHANGELOG maintained
+    section: S1
+    section_title: Repository & Project Structure
+    severity: MEDIUM
+    class: documentation
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check:
+      kind: any_file
+      patterns: ['CHANGELOG*', 'CHANGES*', 'HISTORY.md']
+    why: 'Users and downstream maintainers need to know what changed and whether it will break them.'
+    remediation: 'Adopt Keep a Changelog, or generate it from Conventional Commits / Changesets.'
+    references: ['Keep-a-Changelog']
+
+  - id: REPO-011
+    title: CONTRIBUTING guide present
+    section: S1
+    section_title: Repository & Project Structure
+    severity: LOW
+    class: documentation
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check: { kind: any_file, patterns: ['CONTRIBUTING*', 'docs/CONTRIBUTING*'] }
+    why: 'Turns "how do I run the tests?" from an interruption into a link.'
+    remediation: 'Setup, test/lint commands, branch naming, commit convention, review expectations.'
+    references: ['CII-Best-Practices']
+
+  - id: REPO-012
+    title: Code of conduct present
+    section: S1
+    section_title: Repository & Project Structure
+    severity: LOW
+    class: compliance
+    applies_when:
+      not: { fact: 'maturity:prototype' }
+    check: { kind: any_file, patterns: ['CODE_OF_CONDUCT*', 'docs/CODE_OF_CONDUCT*'] }
+    why: 'Sets the floor for interaction and gives maintainers something to point at.'
+    remediation: 'Adopt the Contributor Covenant.'
+    references: ['CII-Best-Practices']
+
+  - id: REPO-013
+    title: .editorconfig present
+    section: S1
+    section_title: Repository & Project Structure
+    severity: LOW
+    class: style
+    check: { kind: file_exists, files: ['.editorconfig'] }
+    why: 'Kills tabs-vs-spaces diffs before they start, across every editor.'
+    remediation: 'Add a 6-line .editorconfig (charset, EOL, indent style/size, trailing whitespace, final newline).'
+
+  - id: REPO-014
+    title: CODEOWNERS assigns review responsibility
+    section: S1
+    section_title: Repository & Project Structure
+    severity: MEDIUM
+    class: operations
+    applies_when: { fact: 'metric:contributors', op: 'gt', value: 2 }
+    check: { kind: any_file, patterns: ['.github/CODEOWNERS', 'CODEOWNERS', 'docs/CODEOWNERS'] }
+    why: 'With more than two contributors, unreviewed-by-default becomes the default.'
+    remediation: 'Add .github/CODEOWNERS mapping paths to teams; require review from code owners on the default branch.'
+    references: ['OpenSSF-Scorecard:Code-Review']
+
+  - id: REPO-015
+    title: Commit history is meaningful
+    section: S1
+    section_title: Repository & Project Structure
+    severity: LOW
+    class: maintainability
+    check: { kind: manual }
+    why: >-
+      Commit messages are the only history most projects ever write down. "fix stuff" costs the next person an afternoon.
+    evidence: 'Last 20 commit messages. Are they descriptive and consistently formatted?'
+    remediation: 'Adopt Conventional Commits; enforce with commitlint in CI.'
+
+  - id: REPO-016
+    title: Branch strategy is defined and stale branches pruned
+    section: S1
+    section_title: Repository & Project Structure
+    severity: LOW
+    class: maintainability
+    applies_when: { fact: 'metric:branches', op: 'gt', value: 3 }
+    check: { kind: manual }
+    why: >-
+      A branching strategy nobody wrote down is a branching strategy nobody follows, and stale branches hide work.
+    evidence: 'Branch list and age of the oldest non-default branch.'
+    remediation: 'Document trunk-based or Git Flow in CONTRIBUTING; delete merged branches; protect the default branch.'
+
+  - id: REPO-017
+    title: Concern separation at the root
+    section: S1
+    section_title: Repository & Project Structure
+    severity: MEDIUM
+    class: maintainability
+    check:
+      kind: any_file
+      patterns: ['src/**', 'app/**', 'lib/**', 'pkg/**', 'internal/**', 'packages/**']
+    why: 'A flat root of 40 files makes ownership and navigation guesswork.'
+    remediation: 'Group by concern (src/, tests/, docs/, scripts/, config/). Monorepos: packages/ or apps/.'
+
+  - id: REPO-018
+    title: Agent instruction file present (AGENTS.md / CLAUDE.md)
+    section: S1
+    section_title: Repository & Project Structure
+    severity: LOW
+    class: documentation
+    check:
+      kind: any_file
+      patterns:
+        [
+          'AGENTS.md',
+          'CLAUDE.md',
+          '.cursorrules',
+          '.github/copilot-instructions.md',
+          'codex.md',
+          '.windsurfrules',
+        ]
+    why: >
+      Coding agents perform measurably better when the repo tells them how to
+      build, test, and what not to touch. It also stops them inventing commands.
+    remediation: 'Add AGENTS.md: setup, build/test/lint commands, conventions, and explicit no-go areas.'
+    references: ['Agent-Skills']