keyword_supporter.cpp
impl/backup/java-statements-2026-11-12/frontend/keyword_supporter.cpp · 263 line(s) · c
// ===========================================================================
// keyword_supporter.cpp -- see keyword_supporter.h.
// ===========================================================================
#include "keyword_supporter.h"
#include "../../ledger/ledger_core.h" // ledger::sha256_hex
#include <sys/stat.h>
#include <sys/types.h>
#include <errno.h>
#include <fstream>
#include <sstream>
#include <map>
#include <filesystem>
#include <system_error>
namespace sleela::frontend {
const std::vector<std::string>& supporterKeywords() noexcept {
static const std::vector<std::string> kw = {
"try", "catch", "throw", "synchronized", "super"
};
return kw;
}
namespace {
// A short, stable digest over the identifying tuple. We keep 16 hex chars (64
// bits) -- long enough to avoid collisions across a repo, short enough for a
// readable folder name.
std::string makeHash(const std::string& keyword, const std::string& relPath,
const std::string& cls, const std::string& method, int ordinal) {
std::string seed = keyword + "|" + relPath + "|" + cls + "::" + method + "|" +
std::to_string(ordinal);
std::string full = ledger::sha256_hex(seed);
return full.substr(0, 16);
}
// Per-method occurrence counters, so the ordinal (and therefore the hash) is
// deterministic for a given keyword within a given method regardless of how the
// walker recurses.
struct Counters {
// keyword -> count seen so far in the current method
int next(const std::string& keyword) { return counts_[keyword]++; }
private:
std::map<std::string, int> counts_;
};
class Walker {
public:
Walker(const std::string& relPath, std::vector<KeywordSupporterRecord>& out)
: relPath_(relPath), out_(out) {}
void walkProgram(const Program& prog) {
for (const auto& cls : prog.classes) {
for (const auto& m : cls.methods) {
cls_ = cls.name;
method_ = m.name.empty() ? std::string("<init>") : m.name;
counters_ = Counters{};
if (m.body) walkBlock(*m.body);
}
}
}
private:
void record(const std::string& keyword) {
KeywordSupporterRecord r;
r.keyword = keyword;
r.enclosingClass = cls_;
r.enclosingMethod = method_;
r.ordinal = counters_.next(keyword);
r.relSourcePath = relPath_;
r.hash = makeHash(keyword, relPath_, cls_, method_, r.ordinal);
out_.push_back(std::move(r));
}
void walkBlock(const Block& b) {
for (const auto& s : b.stmts) walkStmt(s.get());
}
void walkStmt(const Stmt* s) {
if (!s) return;
// Keyword-bearing statements first, then recurse into their sub-trees.
if (auto t = dynamic_cast<const TryStmt*>(s)) {
record("try");
if (t->body) walkBlock(*t->body);
for (const auto& c : t->catches) { record("catch"); if (c.body) walkBlock(*c.body); }
if (t->finallyBlock) walkBlock(*t->finallyBlock);
return;
}
if (auto th = dynamic_cast<const ThrowStmt*>(s)) { record("throw"); walkExpr(th->value.get()); return; }
if (auto sy = dynamic_cast<const SynchronizedStmt*>(s)) {
record("synchronized");
walkExpr(sy->monitor.get());
if (sy->body) walkBlock(*sy->body);
return;
}
// Non-keyword statements: recurse into nested statements/expressions so
// keywords buried inside control flow are still discovered.
if (auto b = dynamic_cast<const Block*>(s)) { walkBlock(*b); return; }
if (auto v = dynamic_cast<const VarDecl*>(s)) { walkExpr(v->init.get()); return; }
if (auto a = dynamic_cast<const Assign*>(s)) { walkExpr(a->value.get()); return; }
if (auto fa = dynamic_cast<const FieldAssign*>(s)) { walkExpr(fa->base.get()); walkExpr(fa->value.get()); return; }
if (auto es = dynamic_cast<const ExprStmt*>(s)) { walkExpr(es->expr.get()); return; }
if (auto ps = dynamic_cast<const PrintStmt*>(s)) { walkExpr(ps->expr.get()); return; }
if (auto rs = dynamic_cast<const ReturnStmt*>(s)) { walkExpr(rs->value.get()); return; }
if (auto i = dynamic_cast<const IfStmt*>(s)) { walkExpr(i->cond.get()); walkStmt(i->thenS.get()); walkStmt(i->elseS.get()); return; }
if (auto w = dynamic_cast<const WhileStmt*>(s)) { walkExpr(w->cond.get()); walkStmt(w->body.get()); return; }
if (auto f = dynamic_cast<const ForStmt*>(s)) { walkStmt(f->init.get()); walkExpr(f->cond.get()); walkStmt(f->update.get()); walkStmt(f->body.get()); return; }
if (auto d = dynamic_cast<const DoStmt*>(s)) { walkStmt(d->body.get()); walkExpr(d->cond.get()); return; }
if (auto as = dynamic_cast<const AssertStmt*>(s)) { walkExpr(as->cond.get()); walkExpr(as->message.get()); return; }
if (auto y = dynamic_cast<const YieldStmt*>(s)) { walkExpr(y->value.get()); return; }
if (auto sw = dynamic_cast<const SwitchStmt*>(s)) {
walkExpr(sw->selector.get());
for (const auto& c : sw->cases) {
for (const auto& lab : c.labels) walkExpr(lab.get());
for (const auto& st : c.statements) walkStmt(st.get());
}
return;
}
// VarDecl-less / leaf statements (Break, Continue, GcHint): nothing to do.
}
void walkExpr(const Expr* e) {
if (!e) return;
if (dynamic_cast<const SuperExpr*>(e)) { record("super"); return; }
if (auto u = dynamic_cast<const Unary*>(e)) { walkExpr(u->operand.get()); return; }
if (auto b = dynamic_cast<const Binary*>(e)) { walkExpr(b->lhs.get()); walkExpr(b->rhs.get()); return; }
if (auto c = dynamic_cast<const Call*>(e)) { for (const auto& a : c->args) walkExpr(a.get()); return; }
if (auto mc = dynamic_cast<const MethodCall*>(e)) { walkExpr(mc->receiver.get()); for (const auto& a : mc->args) walkExpr(a.get()); return; }
if (auto ne = dynamic_cast<const NewExpr*>(e)) { for (const auto& a : ne->args) walkExpr(a.get()); return; }
if (auto ma = dynamic_cast<const MemberAccess*>(e)) { walkExpr(ma->base.get()); return; }
if (auto ae = dynamic_cast<const AssignmentExpr*>(e)) { walkExpr(ae->target.get()); walkExpr(ae->value.get()); return; }
if (auto ce = dynamic_cast<const ConditionalExpr*>(e)) { walkExpr(ce->cond.get()); walkExpr(ce->thenE.get()); walkExpr(ce->elseE.get()); return; }
if (auto io = dynamic_cast<const InstanceOfExpr*>(e)) { walkExpr(io->value.get()); return; }
if (auto cx = dynamic_cast<const CastExpr*>(e)) { walkExpr(cx->operand.get()); return; }
if (auto aa = dynamic_cast<const ArrayAccess*>(e)) { walkExpr(aa->base.get()); walkExpr(aa->index.get()); return; }
if (auto mr = dynamic_cast<const MethodReferenceExpr*>(e)) { walkExpr(mr->base.get()); return; }
if (auto gc = dynamic_cast<const GuideChainExpr*>(e)) { walkExpr(gc->head.get()); return; }
// Leaf expressions (literals, VarExpr, ThisExpr, NullLit, RanRefExpr).
}
std::string relPath_;
std::vector<KeywordSupporterRecord>& out_;
std::string cls_, method_;
Counters counters_;
};
// Create a directory tree using the host filesystem semantics. This handles
// POSIX separators, Windows drive roots, and existing directories uniformly.
bool ensureDir(const std::string& path) {
if (path.empty()) return true;
std::error_code ec;
std::filesystem::create_directories(std::filesystem::path(path), ec);
if (ec) return false;
return std::filesystem::is_directory(std::filesystem::path(path), ec) && !ec;
}
bool fileExists(const std::string& path) {
struct stat st; return stat(path.c_str(), &st) == 0;
}
std::string supportStub(const KeywordSupporterRecord& r) {
std::ostringstream o;
o << "<< ---- Descriptive metadata (version 1.11 nested-friendly accessors) ----\n"
<< " metaVersion \"1.0.0\"\n"
<< " metaId none\n"
<< " metaAuthor unknown < fill in the developer who owns this occurrence >\n"
<< " metaDate unknown < fill in YYYY-MM-DD when documented >\n"
<< " metaCopyright none\n"
<< " metaTrademark none\n"
<< " metaCorporation none\n"
<< " metaOrigin none\n"
<< " metaBirthDate unknown\n"
<< " metaScienceRating 1\n"
<< " metaNationalSchedule none\n"
<< ">>\n\n"
<< "# Supporter document -- `" << r.keyword << "`\n\n"
<< "This document supports one specific use of the `" << r.keyword
<< "` keyword in SLeeLa source. It is linked to that occurrence by the\n"
<< "`@supporter(\"" << r.keyword << ":" << r.hash << "\")` annotation emitted for it.\n\n"
<< "| Field | Value |\n"
<< "|-------|-------|\n"
<< "| Keyword | `" << r.keyword << "` |\n"
<< "| Hash | `" << r.hash << "` |\n"
<< "| Source | `" << r.relSourcePath << "` |\n"
<< "| Enclosing | `" << r.enclosingClass << "::" << r.enclosingMethod << "` |\n"
<< "| Occurrence | #" << r.ordinal << " of `" << r.keyword
<< "` in that method |\n\n"
<< "> This stub was generated automatically. Fill in the sections below; it\n"
<< "> is never overwritten once it exists.\n\n"
<< "## Intent\n\n"
<< "_Why does this `" << r.keyword << "` exist here? What is it protecting or expressing?_\n\n"
<< "## Behavior\n\n"
<< "_What is the expected runtime behavior (control flow, values, side effects)?_\n\n"
<< "## Invariants\n\n"
<< "_What must hold before and after? What must never happen?_\n\n"
<< "## Notes\n\n"
<< "_References, related occurrences, open questions._\n";
return o.str();
}
} // namespace
std::vector<KeywordSupporterRecord>
collectKeywordSupporters(const Program& prog, const std::string& relSourcePath) {
std::vector<KeywordSupporterRecord> out;
Walker w(relSourcePath, out);
w.walkProgram(prog);
return out;
}
void attachSupporterAnnotations(Program& prog,
const std::vector<KeywordSupporterRecord>& records) {
for (const auto& r : records) {
std::string value = r.keyword + ":" + r.hash;
// Skip if an identical supporter annotation is already present.
bool dup = false;
for (const auto& a : prog.annotations.all()) {
if (a.name == "supporter" && a.value == value) { dup = true; break; }
}
if (!dup) prog.annotations.add(std::string("supporter"), value);
}
}
bool materializeSupporterFolders(const std::vector<KeywordSupporterRecord>& records,
const std::string& docsRoot) {
if (records.empty()) return true;
const std::string base = docsRoot + "/keyword-supporters";
if (!ensureDir(base)) return false;
for (const auto& r : records) {
std::string dir = base + "/" + r.keyword + "/" + r.hash;
if (!ensureDir(dir)) return false;
std::string doc = dir + "/SUPPORT.md";
if (!fileExists(doc)) { // never overwrite developer content
std::ofstream f(doc);
if (!f) return false;
f << supportStub(r);
}
}
// Refresh a simple index listing every known occurrence. The index is
// generated output, so it IS rewritten each run.
std::ofstream idx(base + "/INDEX.md");
if (idx) {
idx << "# Keyword supporter documents\n\n"
<< "Generated index of `try` / `catch` / `throw` / `synchronized` / `super`\n"
<< "occurrences and their supporter folders. Each row's folder holds a\n"
<< "`SUPPORT.md` for a developer to fill out; this index is regenerated\n"
<< "on each compile.\n\n"
<< "| Keyword | Hash | Source | Enclosing | # |\n"
<< "|---------|------|--------|-----------|---|\n";
for (const auto& r : records) {
idx << "| `" << r.keyword << "` | [`" << r.hash << "`](" << r.keyword
<< "/" << r.hash << "/SUPPORT.md) | `" << r.relSourcePath << "` | `"
<< r.enclosingClass << "::" << r.enclosingMethod << "` | " << r.ordinal
<< " |\n";
}
}
return true;
}
} // namespace sleela::frontend