Polish the repo for open-source readiness (relicense to Apache-2.0, fix documented crashes and leaks)

.editorconfig

@@ -0,0 +1,31 @@
+# https://editorconfig.org
+# Mirrors .clang-format (Google style, 2-space indent, 80 columns).
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.{c,h,cc,cpp,hpp}]
+indent_size = 2
+max_line_length = 80
+
+[*.py]
+indent_size = 4
+
+[*.{yml,yaml,json,js,cmake}]
+indent_size = 2
+
+[CMakeLists.txt]
+indent_size = 2
+
+[Makefile]
+indent_style = tab
+
+[*.md]
+# trailing double-space is a hard line break in Markdown
+trim_trailing_whitespace = false

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,36 @@
+<!-- Thanks for contributing to libCacheSim! See CONTRIBUTING.md for the full guide. -->
+
+## What does this PR do?
+
+<!-- A short description of the change and the motivation behind it.
+     Link any related issue, e.g. "Fixes #123". -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New eviction / admission / prefetch algorithm
+- [ ] New trace reader or trace format
+- [ ] Performance improvement
+- [ ] Documentation
+- [ ] Build / CI
+- [ ] Other:
+
+## How was it tested?
+
+<!-- The commands you ran. Sample traces live in data/, e.g.
+     cd _build && ./bin/cachesim ../data/cloudPhysicsIO.vscsi vscsi lru 1gb -->
+
+- [ ] `ctest --test-dir _build --output-on-failure` passes
+- [ ] Build is warning-free (CI uses `-Wall -Wextra -Werror`)
+
+## Results
+
+<!-- If this changes miss ratios or throughput, paste the before/after numbers
+     and the command you used. Delete this section if it does not apply. -->
+
+## Checklist
+
+- [ ] Formatted with `clang-format` (or the pre-commit hook from `scripts/setup_hooks.sh`)
+- [ ] Added or updated tests
+- [ ] Added or updated documentation
+- [ ] New algorithms are registered in the CLI and listed in the [README](../README.md#supported-algorithms)

.github/copilot-instructions.md

@@ -17,7 +17,7 @@
 - Use a standard out-of-source CMake build for release-style work: `cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release` then `cmake --build build`.
 - CMake tests are enabled by default. Run `ctest --test-dir _build_dbg --output-on-failure` after the debug build, or the equivalent `build/` test directory if you used a separate build tree.
 - If you change installation, packaging, or the public library surface, also review `test/test_lib.sh`.
-- Use sample traces in `data/` for quick validation unless the task specifically requires the large traces in `2024_google/`.
+- Use sample traces in `data/` for quick validation. They are deliberately tiny, so never use them to compare miss ratios between algorithms; larger traces are listed at https://github.com/cacheMon/cache_dataset.
 
 ## Project-Specific Conventions
 - When adding a new eviction algorithm, reader, or plugin, follow `doc/advanced_lib_extend.md` instead of inventing a new integration path. These changes usually require updates to implementation files, registration headers, CMake lists, CLI/parser wiring, and tests.

.github/workflows/build.yml

@@ -15,6 +15,8 @@ jobs:
     runs-on: macos-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       - name: Prepare
         run: bash scripts/install_dependency.sh
       - name: Configure CMake
@@ -29,6 +31,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       - name: Prepare
         run: bash scripts/install_dependency.sh
       - name: Configure CMake with LSan

.github/workflows/code-quality.yml

@@ -10,9 +10,10 @@ jobs:
     name: Code Quality Checks
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0  # Fetch all history for proper git diff
+          persist-credentials: false
 
       - name: Install dependencies
         run: |

.github/workflows/codeql-analysis.yml

@@ -25,6 +25,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+        with:
+          persist-credentials: false
 
       - name: Initialize CodeQL
         uses: github/codeql-action/init@v4

.github/workflows/npm-release.yml

@@ -29,6 +29,8 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          persist-credentials: false
 
       - name: Synchronize Node.js binding version
         run: |
@@ -57,29 +59,29 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+      # actions/create-release was archived by GitHub in 2021; the gh CLI is
+      # preinstalled on the runners and is already used by the step above.
       - name: Create GitHub Release
         id: release
         if: steps.check_release.outputs.exists == 'false'
-        uses: actions/create-release@v1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          tag_name: v${{ steps.package.outputs.version }}
-          release_name: Release v${{ steps.package.outputs.version }}
-          body: |
-            Release v${{ steps.package.outputs.version }}
+          VERSION: ${{ steps.package.outputs.version }}
+        run: |
+          gh release create "v${VERSION}" \
+            --title "Release v${VERSION}" \
+            --notes "Release v${VERSION}
 
-            ## Installation
-            ```bash
-            npm install libcachesim-node
-            ```
+          ## Installation
+          \`\`\`bash
+          npm install libcachesim-node
+          \`\`\`
 
-            ## Supported Platforms
-            - Linux x64
+          ## Supported Platforms
+          - Linux x64
 
-            Pre-compiled binaries are automatically downloaded during installation.
-          draft: false
-          prerelease: false
+          Pre-compiled binaries are automatically downloaded during installation."
+          echo "release_created=true" >> "$GITHUB_OUTPUT"
 
   build-and-publish:
     if: github.event_name == 'release'
@@ -92,6 +94,7 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
+          persist-credentials: false
           fetch-depth: 0
 
       - name: Synchronize Node.js binding version
@@ -157,6 +160,8 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          persist-credentials: false
 
       - name: Synchronize Node.js binding version
         run: |

.gitignore

@@ -1,24 +1,37 @@
-# 1a1a11a
-__pycache__
-*deprecated*
-*.DS_Store*
-*.bak
-*.clean
-*.nogit*
+# Build output
+build
 *_build*
+example/cacheSimulatorC/cmake-build-debug
 *.out
-build
+*.whl
+
+# Editors and IDEs
 .idea
-example/cacheSimulatorC/cmake-build-debug
+sftp-config.json
+# the checked-in .vscode/*.json files are shared editor config; ignore the rest
 .vscode/*
+!.vscode/c_cpp_properties.json
+!.vscode/launch.json
+!.vscode/settings.json
+!.vscode/tasks.json
+
+# Caches and generated files
+doc/_build/
+__pycache__
+*.cache/
+.lint-logs/
 *.log
+*.DS_Store*
+
+# Scratch and local data
+*deprecated*
+*.bak
+*.clean
+*.nogit*
 fig/
 result/
 data_large/
-# Chaos
-sftp-config.json
-# Clangd cache
-*.cache/
-.lint-logs/
-# Python wheels
-*.whl
+
+# Traces produced by traceConv/traceFilter when run against data/
+data/*.oracleGeneral
+data/*.lcs.*

.readthedocs.yaml

@@ -11,13 +11,14 @@ build:
   tools:
     python: "3.11"
 
-# Build documentation in the docs/ directory with Sphinx
+# The documentation sources are the Markdown files in doc/, rendered with MyST.
 sphinx:
-  configuration: docs/conf.py
+  configuration: doc/conf.py
+  # The build is warning-free; keep it that way, since a broken cross-reference
+  # is otherwise easy to miss.
+  fail_on_warning: true
 
-# We recommend specifying your dependencies to enable reproducible builds:
-# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# Docs-only dependencies; the root requirements.txt is for the analysis scripts.
 python:
   install:
-  - requirements: requirements.txt
-
+    - requirements: doc/requirements.txt

CITATION.cff

@@ -0,0 +1,121 @@
+cff-version: 1.2.0
+title: libCacheSim
+message: >-
+  If you use libCacheSim in your research, please cite the
+  software and the relevant papers below.
+type: software
+authors:
+  - family-names: Yang
+    given-names: Juncheng
+    affiliation: Harvard University
+repository-code: 'https://github.com/1a1a11a/libCacheSim'
+abstract: >-
+  A high-performance library and set of tools for building
+  and running cache simulations, analyzing cache traces, and
+  profiling miss ratio curves.
+keywords:
+  - cache
+  - caching
+  - cache simulation
+  - eviction algorithm
+  - miss ratio curve
+  - trace analysis
+license: Apache-2.0
+preferred-citation:
+  type: conference-paper
+  title: FIFO Queues Are All You Need for Cache Eviction
+  authors:
+    - family-names: Yang
+      given-names: Juncheng
+    - family-names: Zhang
+      given-names: Yazhuo
+    - family-names: Qiu
+      given-names: Ziyue
+    - family-names: Yue
+      given-names: Yao
+    - family-names: Rashmi
+      given-names: K. V.
+  collection-title: >-
+    Proceedings of the 29th Symposium on Operating Systems
+    Principles (SOSP '23)
+  publisher:
+    name: Association for Computing Machinery
+  year: 2023
+  start: 130
+  end: 149
+  isbn: '9798400702297'
+  doi: 10.1145/3600006.3613147
+references:
+  - type: conference-paper
+    title: >-
+      A large-scale analysis of hundreds of in-memory cache
+      clusters at Twitter
+    authors:
+      - family-names: Yang
+        given-names: Juncheng
+      - family-names: Yue
+        given-names: Yao
+      - family-names: Rashmi
+        given-names: K. V.
+    collection-title: >-
+      14th USENIX Symposium on Operating Systems Design and
+      Implementation (OSDI 20)
+    publisher:
+      name: USENIX Association
+    year: 2020
+    month: 11
+    start: 191
+    end: 208
+    isbn: '978-1-939133-19-9'
+    url: 'https://www.usenix.org/conference/osdi20/presentation/yang'
+  - type: conference-paper
+    title: >-
+      FIFO Can Be Better than LRU: The Power of Lazy
+      Promotion and Quick Demotion
+    authors:
+      - family-names: Yang
+        given-names: Juncheng
+      - family-names: Qiu
+        given-names: Ziyue
+      - family-names: Zhang
+        given-names: Yazhuo
+      - family-names: Yue
+        given-names: Yao
+      - family-names: Rashmi
+        given-names: K. V.
+    collection-title: >-
+      Proceedings of the 19th Workshop on Hot Topics in
+      Operating Systems (HotOS '23)
+    publisher:
+      name: Association for Computing Machinery
+    year: 2023
+    start: 70
+    end: 79
+    isbn: '9798400701955'
+    doi: 10.1145/3593856.3595887
+  - type: conference-paper
+    title: >-
+      SIEVE is Simpler than LRU: an Efficient Turn-Key
+      Eviction Algorithm for Web Caches
+    authors:
+      - family-names: Zhang
+        given-names: Yazhuo
+      - family-names: Yang
+        given-names: Juncheng
+      - family-names: Yue
+        given-names: Yao
+      - family-names: Vigfusson
+        given-names: Ymir
+      - family-names: Rashmi
+        given-names: K. V.
+    collection-title: >-
+      21st USENIX Symposium on Networked Systems Design and
+      Implementation (NSDI 24)
+    publisher:
+      name: USENIX Association
+    year: 2024
+    month: 4
+    start: 1229
+    end: 1246
+    isbn: '978-1-939133-39-7'
+    url: 'https://www.usenix.org/conference/nsdi24/presentation/zhang-yazhuo'