danabra.mov / typelex
An experimental TypeSpec syntax for Lexicon
fork atom

claude

danabra.mov 790b113f 720408d9

deploy.yaml
+11 -34
unified split
+11 -34
CLAUDE.md
··· 1 - you're working on a TypeSpec emitter for atproto lexicons. you have these commands: `pnpm run build` builds the example (you can inspect the generated lexicons in the `packages/example/lexicon`) and `pnpm test` runs tests (they are in `packages/emitter/test/`). 1 + you're working on a TypeSpec emitter for atproto Lexicons. the goal is to make a more comfortable language for writing lexicons, kind of like "coffeescript for lexicons" (however terrible that may be). one may imagine it getting supplanted by a proper atproto IDL someday. however, we're staying within what TypeSpec offers, which means we want to stay idiomatic both to atproto and TypeSpec, or rather, to try to translate atproto idioms into TypeSpec idioms as closely as we can. 2 2 3 - what i want you to do is to gradually keep adding features to typelex so that in the end it's possible to express all Lexicon code with that language. you have the following resources: 3 + you have the following resources you're encouraged to explore on your own whenever they seem relevant to the task: 4 4 5 - - read `DOCS.md`!!! it's the main guideline 5 + - `DOCS.md` is a must-read. it gives you an intro to typelex and how its conventions map to atproto. it also gives you a sense of the project philosophy. 6 + - `../atproto-website/` has a Lexicon spec (look for `lexicon/en.mdx`) which you'll want to consult 7 + - `../typespec/` is the TypeSpec repo. you can consult the source code of other emitters (in `packages`, e.g. `packages/protobuf` and `packages/json-schema`) and `website` folder for documentation of TypeSpec syntax and idioms. 6 8 7 - - `../typespec/packages` has a bunch of other emitters (so you can check how they're implemented and common patterns) 9 + as a part of your workflow, you will: 8 10 9 - - `../typespec/website/src/content` has typescpec docs (which you might find very useful) 11 + - run `pnpm test` whenever you make changes to verify no regressions. note a few test suites: an `atproto` test suite with definitions from upstream (`.tsp` files produce expected `.json` files), `lexicon-examples` suite with third party lexicons, and `spec` with a more focused suite. use checked-in `*.tsp` files liberally to learn typelex conventions. we have a LOT of them! 10 12 11 - - `../atproto-website/src/app/[locale]/specs/lexicon` contains lexicon spec (where we want to reach feature parity), and most importantly 13 + - if you're working on `packages/example`, use `pnpm run build` to run it and observe the output. you may also want to look at codegen output (it's hooked up to atproto codegen). 12 14 13 - - `test/scenarios/atproto/output` contains a TON of lexicon definitions which i want you to translate to typespec one by one. for each atproto lexicon you're porting, your job is to create the corresponding "`input`s" for them (and fix bugs or add missing features along the way). 15 + - we also have a playground in `packages/playground` and website in `packages/website`. 14 16 15 - the goal is to end up with a language that feels nice and concise, not some weird interop thing. so try to do things "typespec" way as you go through each lexicon. and try to respect atproto too. this should feel like a *language for atproto*. consider whether your design is elegant. and make sure to look at other typespec emitters for design ideas! 16 - 17 - remember NOT to change the output to fit the input -- your job is to make the input MATCH the output. if some lexicon is too hard, you can give up on it and try another one. good luck! 18 - 19 - the workflow is: pick some new lexicons, create the input files, figure out missing features / bugs, and try to get tests to pass. repeat. when you make nontrivial progress, you'll want to prepare a commit. 20 - 21 - before you want to make a commit, make sure `pnpm test` and `pnpm run build` passes and, ideally, inspect the `example` app output (and maybe add the features you've just implemented there for parity). then stop and notify me. 22 - 23 - ps. be mindful of the code style. we only put decorators on same line if it's `@required` alone; otherwise, put each on newline and add a newline after. see existing files for a hint. 17 + you'll approach the project thoughtfully. while `playground` and `website` are more vibey and can be garbage code, it's essential to keep the `emitter` making sense. this doesn't just mean always verifying the tests pass (that's a given), but also making each decision *based on the spec* and a good understanding of atproto semantics. always think: is this the simplest solution? does it still make sense if you forget the code that exists now and think from first principles? don't hesitate to pause and ask or rethink if something actually doesn't make sense. 24 18 25 19 good luck! i believe in you 26 20 27 - 28 - --- 29 - 30 - whenever you get stuck (try `npm test`) because you don't have a convention for how to define some pattern yetm i want you to read these sources 31 - 32 - - `../typespec/packages` has a bunch of other emitters (so you can check how they're implemented and common patterns) 33 - 34 - - `../typespec/website/src/content` has typescpec docs (which you might find very useful) 35 - 36 - - `../atproto-website/src/app/[locale]/specs/lexicon` contains lexicon spec 37 - 38 - and ultrathink about what's the most appropriate way to define defs like you want would be in this typespec translation of atproto. you can research these sources for what feels most idiomatic to define that syntax, and how to make 39 - the formatter understand that convention and emit the JSON we want. 40 - 41 - also note that you can always look at generated atproto lexicons in ../atproto/lexicons -- use these!! look at the TS types there for corresponding 42 - models to inspire how you represent things in tsp syntax. 43 - 44 - - read `DOCS.md`!!! it's the main guideline 21 + and read the `DOCS.md` (and `*.tsp` files in this repo)!!! they're your most important sources of information.